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, declared as the bascik bin in package.json. It resolves arguments using cli.ts and dispatches action requests accordingly:

// index.ts (entry point)
const args = process.argv.slice(2);
const decision = resolveCliAction(args);

switch (decision.action) {
  case "init": {
    const { initProject } = await import("./lib/init.js");
    await initProject();
    process.exit(0);
  }
  case "check": {
    const { checkProject } = await import("./lib/check.js");
    const ok = await checkProject();
    process.exit(ok ? 0 : 1);
  }
  case "prodServer": {
    const { serveProduction } = await import("./lib/serve.js");
    await serveProduction();
    break;
  }
  default:
    await import("./transpile.js");
}

transpile.ts handles the normal dev and build flow. In build mode it awaits watchFiles() and exits. In dev mode it starts server.ts concurrently with watchFiles(), so the server is already bound to its port by the time transpilation finishes. startServer() orchestrates loading either http.ts or http2.ts based on BascikConfig.prodServer.enableTls and returns the origin URL; transpile.ts prints Server running at … immediately after the transpilation summary line.

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
  ├── (--serve / prod server)
  │     └── serve.ts → server.ts
  └── transpile.ts
        ├── config.ts ← userConfig.ts ← bascik.config.ts / bascik.config.js
        ├── watch.ts
        │     └── processing.ts
        │           ├── components.ts ← file-system.ts
        │           ├── javascript.ts
        │           │     ├── styles.ts
        │           │     └── names.ts
        │           ├── styles.ts
        │           ├── html-minifier.ts, css-minifier.ts, js-minifier.ts
        │           ├── build-scripts.ts
        │           ├── worker-pool.ts → page-worker.ts
        │           │     └── (transpilePage - no side effects)
        │           ├── mem.ts ← paths.ts
        │           └── events.ts
        └── (dev server, concurrent with watch.ts)
              └── server.ts
                    ├── (if enableTls: true)
                    │     ├── pki.ts
                    │     └── http2.ts ← server-scripts.ts, mem.ts, events.ts, paths.ts, mime.ts
                    └── (default HTTP/1.1)
                          └── http.ts ← server-scripts.ts, mem.ts, events.ts, paths.ts, mime.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.

No runtime framework

Bascik has a single runtime dependency: chokidar for file watching. Everything else uses Node.js built-ins (node:fs, node:http2, node:crypto, node:zlib). This keeps the install footprint minimal 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). 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 24's native TypeScript support. At runtime, Node 24 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.

CPU-aware worker pool (opt-in)

When useWorkers: true is set in bascik.config.ts (default false), processAllPages() creates Math.min(os.cpus().length, pageCount) worker threads via worker-pool.ts instead of transpiling sequentially on the main thread. Each worker is initialized once with the pre-computed componentList and globalStylesHtml, then reused for every page assigned to it. The main thread dispatches page paths through the pool's task queue and collects results to apply side effects (memory storage, event emission) after all workers complete.

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 useWorkers 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 HTTP/2 server can serve the updated page immediately. Disk writes are skipped entirely in dev, dist/ is only written during --build.

Process-isolated script execution

Both <script data-bascik-build> (run at build time) and <script data-bascik-server> (run at request time) are executed in complete isolation. Instead of using eval or Node's vm module, which can leak state or restrict standard Node.js APIs, Bascik writes script content to a temporary .mjs file on disk and runs it as a standalone Node.js subprocess. This process-level isolation ensures that user scripts cannot pollute the memory of the compiler or server, natively supports ES modules, top-level await, dynamic imports, and captures stdout cleanly before removing the temporary files. To maintain accurate debugging diagnostics across process boundaries, Bascik appends //# sourceURL directives and cleans child-process stack traces, mapping temporary .mjs paths and line offsets back to the original source 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. 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.