This document explains the comprehensive build constraints, transformations, and code management strategies in Glimmer VM. It serves as a reference for understanding how code is transformed from development to production and as a starting point for further analysis of the build system.

Glimmer VM uses several categories of code that have different constraints on where they can appear:

1. **Production Code** - Ships to end users in production builds

2. **Development Code** - Available in development builds for end users

3. **Local Development Code** - Only for Glimmer VM developers, never ships

4. **Build-Time Code** - Used during compilation but not at runtime

**What it is**: A de facto standard created by Vite for build-time environment variables.

**Usage in Glimmer VM**:

- `import.meta.env.DEV` - `true` in development builds, `false` in production

- `import.meta.env.PROD` - `true` in production builds, `false` in development

- `import.meta.env.VM_LOCAL_DEV` - `false` in published builds, `true` in Vite dev server

**Constraint**: These references are replaced at build time with actual values. The string `import.meta.env` never appears in published builds.

**What it is**: A build-time flag for code that should only run during local Glimmer VM development.

**Purpose**: Enables expensive debugging features when working on the VM itself. These features never reach published packages (not even development builds).

**Example Usage**:

if (VM_LOCAL) {

// Expensive validation that helps VM developers

validateOpcodeSequence(opcodes);

}

**Constraint**: Code blocks guarded by `VM_LOCAL` are completely removed from all published builds. The condition and its contents are stripped out.

**What they are**: Runtime type checking and validation functions from `@glimmer/debug`:

- `check(value, checker)` - Validates a value against a type checker

- `expect(value, message)` - Asserts a condition is truthy

- `localAssert(condition, message)` - Development-only assertion

- `unwrap(value)` - Unwraps optional values, throwing if null/undefined

**Purpose**: Catch bugs during Glimmer VM development by validating assumptions about types and state.

**Example Usage**:

import { check } from '@glimmer/debug';

import { CheckReference } from './-debug-strip';

let definition = check(stack.pop(), CheckReference);

let capturedArgs = check(stack.pop(), CheckCapturedArguments);

**Constraint**: These function calls are stripped from ALL published builds (both development and production) using a Babel plugin during the build process.

**What they are**: Functions that create runtime type validators:

- `CheckInterface` - Validates object shape

- `CheckOr` - Union type validation

- `CheckFunction` - Function type validation

- `CheckObject` - Object/WeakMap key validation

**Purpose**: Define the type constraints used by `check()` calls.

**Example Usage**:

export const CheckReference: Checker<Reference> = CheckInterface({

[REFERENCE]: CheckFunction,

});

export const CheckArguments = CheckOr(CheckObject, CheckFunction);

**Constraint**: These should never appear in published builds as they're only used by the stripped `check()` calls.

Three private packages contain development-only utilities:

- **@glimmer/debug** - Type checkers, validation utilities, debugging tools

- **@glimmer/constants** - VM opcodes, DOM constants (inlined during build)

- **@glimmer/debug-util** - Debug assertions, platform-specific logging

**Constraint**: These packages are never published to npm. Import statements for them should never appear in published builds - their contents are either inlined or stripped during compilation.

The build process uses a Babel plugin (`@glimmer/local-debug-babel-plugin`) that:

1. Identifies imports from `@glimmer/debug`

2. Tracks which debug functions are imported

3. Strips or transforms the function calls:

- `check(value, checker)` → `value`

- `expect(...)` → removed entirely

- `CheckInterface(...)` → `() => true`

- `recordStackSize()` → removed entirely

The Rollup replace plugin performs these build-time replacements:

**Production builds:**

- `import.meta.env.MODE` → `"production"`

- `import.meta.env.DEV` → `false`

- `import.meta.env.PROD` → `true`

- `import.meta.env.VM_LOCAL_DEV` → `false`

**Development builds:**

- `import.meta.env.MODE` → `"development"`

- `import.meta.env.DEV` → `DEBUG` (with `import { DEBUG } from '@glimmer/env'` injected)

- `import.meta.env.PROD` → `!DEBUG`

- `import.meta.env.VM_LOCAL_DEV` → `false` (becomes `true` only in Vite dev server)

The build system has specific rules for what gets inlined vs treated as external:

**Always Inlined:**

- `@glimmer/local-debug-flags`

- `@glimmer/constants`

- `@glimmer/debug`

- `@glimmer/debug-util`

- Relative imports (`.`, `/`, `#`)

- TypeScript helper library (`tslib`)

**Always External:**

- `@handlebars/parser`

- `simple-html-tokenizer`

- `babel-plugin-debug-macros`

- Other `@glimmer/*` packages (to avoid duplication)

- `@simple-dom/*` packages

- `@babel/*` packages

- Node.js built-ins (`node:*`)

Every package produces multiple build artifacts:

1. **Development Build** (`dist/dev/`)

- Readable, formatted code

- Preserves comments

- No variable name mangling

- Includes source maps

2. **Production Build** (`dist/prod/`)

- Minified with Terser (3 passes)

- Aggressive optimizations

- Preserves `debugger` statements (for `{{debugger}}` helper)

- Includes source maps

3. **Type Definitions** (`dist/{dev,prod}/*.d.ts`)

- Generated from TypeScript source

- Rolled up into single files per entry point

4. **CommonJS Build** (optional, `*.cjs`)

- Only generated if package.json includes CommonJS exports

- Follows same dev/prod split

Glimmer VM uses a multi-tiered TypeScript configuration system:

- `tsconfig.base.json` - Shared base configuration

- `tsconfig.json` - Development configuration (looser for better DX)

- `tsconfig.dist.json` - Distribution configuration (stricter for published code)

Packages can declare their strictness level in `package.json`:

{

"repo-meta": {

"strictness": "strict" | "loose"

}

}

This affects which TypeScript compiler options are applied during type checking.

- **Target**: ES2022

- **Module Resolution**: "bundler" mode

- **Isolated Modules**: Required for build performance

- **Exact Optional Properties**: Enforced in distribution builds

- **No Unchecked Indexed Access**: Enforced in distribution builds

The build system uses Turbo for orchestration with these key relationships:

- `prepack` must complete before any builds

- Type checking runs in parallel with builds

- Cache keys include TypeScript configs, source files, and lock files

- `pnpm build:control` - Build all packages using Rollup

- `pnpm repo:prepack` - Prepare packages for publishing

- `pnpm repo:lint:types` - Type check all packages

**Published Package Structure**:

- Only `dist/` directory is included in npm packages

- Conditional exports for dev/prod builds

- `publint` validates package structure before publishing

**Export Configuration**:

{

"exports": {

".": {

"development": "./dist/dev/index.js",

"default": "./dist/prod/index.js"

}

}

}

Note: Private packages (`@glimmer/debug`, `@glimmer/constants`, `@glimmer/debug-util`, and all `@glimmer-workspace/*`) are never published to npm.

- Automated size tracking via GitHub Actions

- Compares dev/prod sizes against main branch

- Reports size changes in PR comments

- Uses `dust` utility for accurate measurements

- **Browser Tests**: Puppeteer with specific Chrome flags

- **Smoke Tests**: 300s timeout (vs 30s for regular tests)

- **BrowserStack**: Cross-browser testing for releases

- **Floating Dependencies**: Special CI job tests against latest deps

1. Type checking (`tsc`)

2. Linting (`eslint`)

3. Unit tests (QUnit/Vitest)

4. Smoke tests

5. Bundle size analysis

6. Package structure validation (`publint`)

- Transforms `import.meta.env.VM_LOCAL_DEV` → `true` for local development

- Pre-bundles test dependencies for performance

- Custom extension resolution order

- Environment-aware rules (console vs non-console packages)

- Strictness based on package metadata

- Test-specific rules for QUnit

- Custom rules for Glimmer-specific patterns

Tools in `bin/fixes/`:

- `apply-eslint-suggestions.js` - Apply ESLint auto-fixes

- `apply-ts-codefixes.js` - Apply TypeScript code fixes

- `apply-suggestions.js` - Apply both types of fixes

1. **Use debug assertions liberally** - They help catch bugs and document assumptions

2. **Don't wrap debug code in conditions** - The build process handles removal

3. **Import from the right place** - Use `@glimmer/debug` imports in VM code

4. **Trust the build process** - Write clear development code; the build makes it production-ready

5. **Respect package boundaries** - Don't import from private packages in public ones

6. **Follow strictness levels** - Adhere to the TypeScript strictness of your package

The Glimmer VM build system enables developers to write defensive, well-instrumented code during development while shipping minimal, performant code to production. Through multiple layers of transformations, validations, and constraints, it ensures debug code never reaches users while maintaining a fast and helpful development experience.