@textmode/build

| | | | | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

@textmode/build owns build, dev, preview, and test tooling for the textmode.js ecosystem. It bundles Vite, Vitest, Terser, jsdom, and the shared GLSL plugin behind one textmode-build command, so consumers no longer install or configure the engines themselves.

Use it to give every repository the same library build, dev server, preview, and test behavior without repeating engine dependencies or config files.

Features

• One package, multiple engines - Vite, Vitest, Terser, jsdom, @vitest/coverage-v8, and @mapwhit/glsl-minify are implementation dependencies, not peer dependencies. Consumers install only @textmode/build.
• One command - textmode-build build, dev, preview, test, and test:watch cover the whole surface.
• Zero config - Conventional library projects need no Vite or Vitest configuration; the shared defineTextmodeLibrary and defineTextmodeProject helpers ship in the package.
• Shared GLSL pipeline - The textmodeGlsl plugin (loading, composition, minification, and identifier coordination) is included.

Installation

npm install -D @textmode/build

No engine dependencies are required.

Usage

Conventional projects create a vite.config.ts that uses the shared library helper:

import { defineTextmodeLibrary } from '@textmode/build';

export default defineTextmodeLibrary({
	globalName: 'TextmodeLibrary',
});

Add-ons with shaders compose the GLSL plugin:

import { defineTextmodeLibrary, textmodeGlsl } from '@textmode/build';

export default defineTextmodeLibrary({
	globalName: 'TextmodeFilters',
	plugins: [
		textmodeGlsl({
			shaderRoots: ['src/shaders'],
			includeRoots: ['src/shaders'],
		}),
	],
});

Projects with a Vitest workspace create a vitest.config.ts:

import { defineTextmodeProject } from '@textmode/build';

export default defineTextmodeProject({
	projects: [
		{
			test: {
				name: 'unit',
				include: ['tests/unit/**/*.test.ts'],
			},
		},
	],
});

Then delegate the standard scripts:

{
	"scripts": {
		"dev": "textmode-build dev --port 5177 --host",
		"build:bundle": "textmode-build build",
		"preview": "textmode-build preview",
		"test": "textmode-build test",
		"test:watch": "textmode-build test:watch",
		"test:unit": "textmode-build test --project unit"
	}
}

Commands

textmode-build build [args...]
textmode-build dev [args...]
textmode-build preview [args...]
textmode-build test [args...]
textmode-build test:watch [args...]

• build runs a production Vite build.
• dev starts the Vite dev server.
• preview starts the Vite preview server.
• test runs Vitest once.
• test:watch runs Vitest in watch mode.

Every argument after the command is forwarded to the underlying engine, so textmode-build test --project unit, textmode-build test --coverage, and textmode-build dev --port 5177 --host work without special handling.

Every command accepts --cwd <directory>, --help, and --version. Exit status 0 means success, 1 means the engine reported a problem, and 2 means the invocation was invalid.

Configuration

Library builds

defineTextmodeLibrary derives the output contract from package.json:

• src/index.ts is the library entry.
• package.json#main must point to ./dist/<name>.umd.js.
• package.json#module must point to ./dist/<name>.esm.js.
• package.json#exports["."] must declare matching import and require outputs.

It emits ESM and UMD bundles with Terser minification, externalizes textmode.js when it is a declared peer dependency, maps the peer to the textmode UMD global, and sets __TEXTMODE_VERSION__ and IS_MINIFIED build constants.

Tests

defineTextmodeProject uses Vitest with a jsdom environment and globals, applies a @ alias to src, and supports projects, coverage, plugins, setupFiles, and custom alias entries. If your test files import from vitest directly, keep vitest as a devDependency for type resolution.

GLSL

textmodeGlsl requires project-relative shaderRoots (and optional includeRoots). It rewrites bare .glsl/.vert/.frag imports into coordinated modules, resolves #include graphs, minifies shaders, and optionally rewrites private host identifiers when hostIdentifiers.sourceRoots is provided.

Related packages

@textmode/build works with the following textmode-tooling packages:

| Package | Relationship | | --------------------------------------------- | ----------------------------------------------------------- | | @textmode/release | Publishes artifacts produced by this package's build script | | @textmode/tsconfig | Library builds compile against the shared TypeScript policy |

License

The @textmode/build package is licensed under the CC0 1.0 Universal.

Acknowledgements

• Vite
  • The bundler and dev server behind textmode-build build, dev, and preview.
  • License: MIT.
• Vitest
  • The test runner behind textmode-build test and test:watch.
  • License: MIT.
• glsl-minify
  • The GLSL minifier used by the shared plugin.
  • License: MIT.