Internals

Internals Overview

Everything you need to work on the Bascik package itself, architecture, the transpilation pipeline, the scoping system, the dev server, and how to run the test suite.

Repository Layout

The monorepo's main top-level folders:

text 
bascik/
  pkg/          ← the @bascik/bascik npm package
    src/
      index.ts        ← CLI entry point
      transpile.ts    ← dev/build startup (called by index.ts)
      lib/            ← all library modules
  create/       ← standalone generator used by `npm create bascik@rc`
  lsp/          ← the @bascik/language-server package
  adapters/     ← deployment adapters, including @bascik/adapter-cloudflare
  docs/         ← this documentation site (a Bascik project itself)
  extensions/   ← editor tooling, including the VS Code extension
  skills/       ← the public agent skills
  examples/     ← example components and a starter site

The pkg/ directory is a self-contained TypeScript project with its own package.json, tsconfig.json, and vite.config.js (used by Vitest).

Quick Start for Contributors

Use Node.js 26, the current LTS (.nvmrc pins it; Node 24 works too), and Yarn 4. The published packages support Node.js 24.21 and newer. The full pkg test suite runs on both lines: two test helpers depend on a V8 13.6 intrinsic and on a verified TLS cleanup callback ordering (Node 24 and 26), and those tests skip on other versions. Clone the repo and install dependencies from the root, Yarn workspaces wires everything up in one step:

sh 
git clone https://github.com/bascikdev/bascik.git
cd bascik
corepack enable
yarn install

Run the test suite across all packages:

sh 
yarn test:all

Or run package-specific unit tests:

sh 
yarn pkg:unit

Build the package (compiles TypeScript to pkg/dist/):

sh 
yarn pkg:build

To work on the docs site with a live-reload dev server:

sh 
yarn pkg:build   # build pkg first
yarn docs:dev     # http://localhost:8080

After any pkg/src/ change, rebuild the package and the docs server will pick it up automatically.

Internals Sub-pages

  • Architecture, module map, responsibilities, and how the files relate to one another.
  • Create App, how the standalone scaffolding CLI is structured and why the generated app uses npm.
  • Transpilation Pipeline, the two-phase page and component pipeline that turns source HTML into deployable output.
  • Scoping System, how IDs, class names, CSS, and JavaScript references are namespaced per component instance.
  • Server Architecture, the HTTP/1.1 and HTTP/2 servers, dev vs prod modes, request script execution, memory store, and live reload.
  • Time Boundaries, why time is a framework architecture boundary, where FrameworkClock is owned, and how timeout behavior is enforced and tested.
  • Diagnostics, static project validation (bascik --check), tag scanning, and stack trace remapping.
  • Minification, zero-dependency HTML, CSS, and JS minification, Base62 identifier hashing, and BYO minifiers.
  • Testing Internals, running tests, coverage, and writing new unit, integration, and E2E tests.
  • Benchmarking & Profiling, throughput microbenchmarks, paired before-and-after compiler comparisons, timeline captures, and runtime profiling.