Internals

Architecture

Bascik is a Node.js CLI tool written in TypeScript. Its source lives entirely in pkg/src/. This page maps every module to its responsibility and explains how they fit together.

Entry Point

pkg/src/index.ts is the CLI entry point, reached through the bascik bin (bin/bascik.js) declared in package.json. It resolves arguments using cli.ts and dispatches action requests accordingly (simplified):

// index.ts (entry point, simplified)
const decision = resolveCliAction(args);

switch (decision.action) {
  case "help":
  case "version":
  case "error":
    // print usage, the version, or the flag error
    break;
  case "init": {
    const { initProject } = await import("./lib/init.ts");
    await initProject({
      yes: decision.flags.yes,
      skills: !decision.flags.noSkills,
    });
    break;
  }
  case "add": {
    const { addComponents } = await import("./lib/add.ts");
    await addComponents(decision.flags.addTargets ?? [], {
      /* force, yes, dryRun */
    });
    break;
  }
  case "check": {
    const { checkProject } = await import("./lib/check.ts");
    const findings = await checkProject({ fix: decision.flags.fix });
    // exit 1 on errors (or on warnings too with --strict)
    break;
  }
  case "server": {
    const { startProdServer } = await import("./lib/server-prod.ts");
    await startProdServer();
    break;
  }
  default: {
    // "dev" and "build"
    const { runTranspile } = await import("./transpile.ts");
    await runTranspile({ exitOnError: true });
  }
}

transpile.ts handles the normal dev and build flow. In build mode it awaits watchFiles() and exits. In dev mode it calls startDevServer() from server-dev.ts, which binds server.ts concurrently with watchFiles(), so the server is already bound to its port by the time transpilation finishes (requests arriving before page transpilation completes receive an in-memory boot page). server-dev.ts and server-prod.ts are deliberately thin: both boot the same shared server.ts, and each holds only what is specific to its mode, so a page that works locally behaves the same when deployed. startServer() orchestrates loading either http.ts or http2.ts based on BascikConfig.http.tls.enabled and returns the origin URL. The server URL is printed after the initial compilation and post phase. Parallel exec tasks do not block dev startup and may log their outcomes later; their completion never triggers compilation.

The dynamic import() calls are intentional: they avoid loading modules when not needed (init and --check exit before reaching transpile.ts; --build never starts the server).

Library Modules

All logic lives in pkg/src/lib/. Each file has a single, well-defined responsibility:

Dependency Graph

The data flow at a high level:

index.ts
  ├── (init only)
  │     └── init.ts
  ├── (--check only)
  │     └── check.ts ← components.ts, file-system.ts
  ├── (--server / prod server)
  │     └── server-prod.ts → server.ts
  └── transpile.ts
        ├── (dev only) server-dev.ts → server.ts
        ├── config.ts ← userConfig.ts ← bascik.config.ts / bascik.config.js
        ├── watch.ts
        │     └── processing.ts
        │           ├── components.ts ← file-system.ts
        │           │     └── typescript.ts
        │           ├── page-transpile.ts
        │           │     ├── component-expansion.ts
        │           │     │     ├── component-expansion-core.ts → component-* markup helpers
        │           │     │     └── scoping-template.ts → javascript.ts, styles.ts, names.ts
        │           │     ├── page-minification.ts → css-minifier.ts, js-minifier.ts
        │           │     ├── html-minifier.ts → html-scanner.ts
        │           │     └── build-scripts.ts, styles.ts, typescript.ts
        │           ├── page-diagnostics.ts
        │           ├── component-manifest.ts (server or stream scripts only)
        │           ├── worker-pool.ts → page-worker.ts
        │           │     └── (transpilePage - no side effects)
        │           ├── mem.ts ← paths.ts
        │           └── events.ts
        └── (dev server, concurrent with watch.ts)
              └── server.ts ← server-scripts.ts, mem.ts, events.ts, paths.ts, mime.ts
                    ├── (if http.tls.enabled: true)
                    │     └── http2.ts → pki.ts
                    └── (default HTTP/1.1)
                          └── http.ts

Key Design Decisions

Frozen config singleton

BascikConfig is initialized once at startup via config.ts and frozen with Object.freeze(). Every module imports this singleton directly. There is no dependency injection, configuration is a module-level constant that is immutable at runtime.

Zero production dependencies

Bascik has zero mandatory production dependencies. Everything at production runtime (bascik --server) and static build time (bascik --build) uses Node.js built-ins (node:fs, node:http2, node:crypto, node:zlib). chokidar is an optional dependency loaded lazily and used solely by the local development server for file watching, and parse5, the other optional dependency, is loaded only by bascik --check to validate the compiled dist/ HTML. This keeps the production install footprint minimal, enables zero-dependency container deployments (via --omit=optional), and eliminates version-conflict surface area for users.

Avoiding ASTs and browser emulation

Bascik does not use abstract syntax trees (ASTs), DOM parsers (e.g. htmlparser2, parse5), or heavy browser emulation environments (such as JSDOM or Puppeteer) during transpilation. Early prototypes explored these paths but quickly hit significant barriers: JSDOM and browser-level emulation added enormous CPU and memory overhead, while full AST construction introduced complex tree-traversal bottlenecks that severely limited performance.

Instead, Bascik uses high-performance, raw-string manipulation powered by targeted regular expressions combined with temporary content masking (e.g. shielding <script>, <style>, and <textarea> tags). Fast .includes() string-existence guards skip regex execution when target markers are absent, and HTML tag boundary scans use O(1) backwards offset lookups (lastIndexOf) rather than full-string slicing to eliminate O(N^2) heap allocations. This regex-first strategy keeps compile times down to single-digit milliseconds per page, ensures zero external package bloat, and aligns with the project philosophy of being lightweight and fast. The Scoping Compatibility page documents the known limitations and edge cases of this regex approach.

Native TypeScript and ESM Compilation

Bascik embraces Node.js's native TypeScript support (Node 24.21 or newer). At runtime, Node natively strips types to execute .ts files (such as bascik.config.ts, user scripts, and tests) without a separate transpilation step.

For package distribution, the source code in pkg/src/ is compiled by tsc using tsconfig.build.json to emit optimized, pure ESM into pkg/dist/. This pre-compilation ensures that consumers can run the CLI with minimal startup overhead, while local tests and TypeScript features are supported via tsconfig.json and Vitest.

Compiled directive scripts (build, routes, server and stream scripts) are also parsed as ES modules at build time, so an early error such as a redeclared let fails the build, not the first request (checkDirectiveModuleSyntax in typescript.ts). Each thread that builds pages parses them in one shared checker, a worker thread of its own that runs vm.SourceTextModule and never links or runs the module, so a build of valid scripts starts no process; only a module that does not parse is checked again with node --check for the located message. When the checker cannot start, crashes or does not answer within 30 seconds, the thread prints one warning and checks each script with a node --check process until the next build, which starts a fresh checker. A check that does not finish within 30 seconds is skipped with a warning that names the file. The checker's stdout and stderr are piped and never read (reading them would hold the process open while it is idle), so it drops its own writes instead of buffering them.

CPU-aware worker pool (opt-in)

When pipeline.workers: true is set in bascik.config.ts (default false), processAllPages() transpiles pages on worker threads via worker-pool.ts instead of sequentially on the main thread. The pool starts as soon as the page list is known, before the component list has loaded and before dynamic routes are expanded, so each worker loads the transpiler's modules while the main thread does that work. It starts with one worker per page, capped by os.cpus().length and the build-script child budget (derived from available memory, which script-runner.ts reads from vm_stat on macOS, where os.freemem() and older process.availableMemory() under-report it), so a small site never loads the transpiler in a worker it will not use. Once expansion has produced the job list the pool is fitted to the job count with the same caps: it grows when a dynamic route expanded to more jobs than there are pages, and is trimmed when a routes script found no routes. A trimmed worker, like every worker when the pool is torn down, is stopped only once it has loaded, and by asking it to end itself (a stop message after which it closes its port and lets its thread exit) rather than by worker.terminate(), which is kept as the fallback for a worker that has not exited after 3 s. Each worker receives the componentList and globalStylesHtml once, in a settings message sent before its first page, then is reused for every page assigned to it. The main thread dispatches page jobs through the pool's task queue and collects results to apply side effects (memory storage, event emission) after all workers complete. Each result's HTML arrives as a transferred Uint8Array rather than a cloned string; the main thread wraps it in a Buffer view and forwards those bytes directly to the in-memory page store and the disk writer without decoding.

Spinning up the pool has a fixed cost, each worker loads the transpiler's module graph independently before it can process its first page. This pays for itself on larger sites with CPU-heavy per-page work, but for small sites (or sites whose slow parts are I/O-bound, like <script data-bascik-build> blocks) sequential transpilation on the main thread is often faster overall. See the pipeline.workers config option.

Memory-first dev serving

In dev mode, pageProcessing() writes the transpiled HTML to the in-memory store and emits the "transpiled" event before writing anything to disk. The server can serve the updated page immediately. The dist/ write is then queued in the background, one write at a time per page, and skipped when a newer edit to that page has superseded it, so serving never waits for file I/O. In --build, each write is awaited.

Canonical page paths

paths.ts is the single source of truth for converting page filenames into canonical URL paths. The in-memory server key, BASCIK_PAGE_PATH build-script value, and sitemap generator all use the same conversion. Directory indexes use a trailing slash, so src/pages/blog/index.html becomes /blog/. Sitemap serialization percent-encodes each segment after canonicalization, while the server decodes incoming paths before lookup.

Process-isolated build scripts vs in-process server scripts

Bascik separates the execution model of build-time scripts from request-time server scripts:

• Build scripts (<script data-bascik-build>): Executed in complete isolation. Instead of using eval or Node's vm module, which can leak state or restrict standard Node.js APIs, Bascik rewrites relative ./ and ../ ESM imports against the source page or component directory and @/ imports against the configured import root (scripts.importRoot), writes build script content to a temporary .mjs file on disk, and runs each uncached script as its OWN standalone Node.js subprocess, bounded by a memory-aware semaphore. There is no shared-process batch: every script gets a fresh ESM module registry, its own stdout/stderr streams, and its own environment, so execution isolation is independent of how many sibling scripts were cache misses. This process-level isolation ensures that user build scripts cannot pollute the memory of the compiler or server, natively supports ES modules, top-level await, dynamic imports, and invokes the callable default export to transport returned HTML cleanly through a separate result channel before removing temporary files.
• Server scripts (<script data-bascik-server>): Executed in-process at request time as Node.js ESM modules via ScriptRegistry. During bascik --build, the script source is extracted into the sidecar (.bascik/dist/server-scripts.json) and replaced in the HTML with an inert placeholder tag (<script type="text/bascik-server" data-bascik-server-id="...">). When bascik --server boots, it loads the sidecar into memory once. Incoming requests execute the registered module in-process with a WHATWG Request and { remoteIp } context and inject the returned markup into the document flow without subprocess spawn overhead. When the returned markup contains component tags, request-render.ts renders them from the component manifest (.bascik/dist/components.json), written by the same build; a script inside such a component is staged in the sidecar like a page script and runs in-process too. See Request-time component rendering.

To maintain accurate debugging diagnostics across execution boundaries, Bascik appends //# sourceURL directives and cleans stack traces (stack-trace.ts), mapping temporary paths and line offsets back to the original source HTML file.

Incremental rebuilds via reverse component index

To keep the development server instantaneous, Bascik avoids full site rebuilds on change. The in-memory store (mem.ts) maintains a reverse dependency index mapping each custom component tag to the exact list of pages that consume it. When a component file is modified, the file-system watcher resolves the component's name, checks the reverse index, and schedules only the affected pages for re-transpilation. A stylesheet that component CSS @imports is mapped to its importing components at listing time (componentsImportingStylesheet), so editing it rebuilds those components' pages too. Unaffected pages remain cached in memory.

Custom lightweight JS minifier

Rather than bundling heavy engines like Terser, esbuild, or SWC as dependencies to minimize scoped scripts and IIFEs, Bascik includes a custom, regex-based segment minifier (js-minifier.ts). It strips comments, collapses redundant whitespace, removes safe operator padding, and respects statement boundaries (ASI) without mutating literal strings or regex patterns. This approach keeps dependencies at zero and avoids any performance impact on transpilation.

Zero-dependency live reload via Server-Sent Events (SSE)

Instead of pulling in a WebSocket dependency like ws or injecting a heavy client library, Bascik implements live reloading via native Server-Sent Events (SSE). The dev server uses a lightweight request handler built on Node's standard http and http2 modules, while pages are injected with a tiny, twenty-line client script that listens via EventSource. This ensures that live reloading is reliable and completely dependency-free, and adds zero footprint to development builds.

Brotli-compressed in-memory cache

To achieve fast response times in both dev and production modes, Bascik keeps transpiled pages in an in-memory store (mem.ts). Storing large raw HTML strings in V8 memory can lead to high memory consumption and GC pressure on large sites. To prevent this, Bascik compresses all cached pages using Node's native node:zlib Brotli implementation. This reduces the dev server's RAM footprint by up to 90% while allowing production environments to stream pre-compressed buffers directly to modern browsers.

CLI startup and package manager overhead

Bascik's Node.js CLI runtime (pkg/dist/index.js) boots and starts transpilation in under 50ms. When invoking commands through monorepo package managers (such as yarn <workspace> <script>), the package manager itself may spend 1.0 to 1.5 seconds loading plugins, parsing configuration files, and resolving workspace dependency graphs before it spawns the Node.js process. The framework's logged completion metrics (e.g. ✓ All tasks completed in Xms and ✓ Build complete in Xms) measure total task execution within the running Node process. For instant CLI execution with sub-50ms startup latency, invoke the compiled binary directly via node (e.g. node ./node_modules/.bin/bascik) or use a lightweight script runner.