Reference

Development Server

Bascik includes a built-in local development server with file watching, incremental re-transpilation, Server-Sent Events (SSE) live reload, and an interactive browser error overlay.

Starting the Dev Server

Run bascik or npm run dev in your project root:

# Start development server
npx bascik
# or if configured in package.json
npm run dev

When started, Bascik:

1. Loads your project configuration from bascik.config.ts.
2. Cleans the output directory (dist/) to remove stale artifacts.
3. Transpiles all pages and components into memory and disk. Pages open in your browser compile first, then the home page, then the rest (see Compile Order).
4. Initializes high-speed filesystem watchers across pages, components, the import root, and custom pipeline.watchPaths.
5. Starts an HTTP development server with live reload on port 8080.

This is the real output of a new project, recorded from the starter site on one machine. Startup takes a fraction of a second, and saving a page afterward rebuilds only that page:

Compile Order

On a large site, the page you are looking at should not wait for the whole site to compile. Whenever the dev server compiles many pages at once, at startup and after a change to a shared component or stylesheet, it works through them in this order:

1. Pages open in a browser tab. Each tab's live-reload connection tells the server which page it shows. These pages compile first and reload as soon as they are ready.
2. The home page (/). It is the page most often opened next, so it compiles right after the open pages. Other directory indexes such as blog/index.html are ordinary pages.
3. Every other page, in file order.

The order is checked again each time a page finishes, not once at the start. A tab that connects after compilation began, such as a tab reconnecting after you restarted the server, moves its page to the front of the pages that have not started yet.

While the first compile is still running, the browser shows a short startup page and reloads into your page as soon as it is ready. bascik --build does not reorder pages.

Linked Static Assets

For projects with many large static assets, enable development-only asset links instead of copies:

export default defineConfig({
  assets: {
    symlink: true,
  },
});

Bascik links unchanged page assets such as images, SVGs, PDFs, fonts, media, JSON, and XML into dist/, then reports linked: in the console. Files Bascik transforms, including configured CSS, JavaScript, and web manifest output, continue to be copied. Production builds always emit regular files, never symlinks.

If a Windows environment does not allow symlink creation, Bascik warns once and falls back to copying. Enable Windows Developer Mode or grant symlink permission to use linked assets there.

CLI Flags

# Start dev server on custom port
bascik --port 3000

Live Reload via Server-Sent Events (SSE)

Bascik injects a lightweight, zero-dependency SSE client into HTML pages served during development.

• When an HTML, CSS, or JavaScript file is saved, Bascik re-transpiles only affected pages and notifies connected browsers via an SSE event stream (/__bascik_sse).
• Browsers reload seamlessly without requiring browser extensions or external polling tools.
• Live reload scripts are completely stripped from production builds (bascik --build).

Here it is on a new project. The first edit changes a page. The second changes the feat-card component, and every card on the page updates because they all use it:

Browser Error Overlay

When a syntax error, build script failure, or invalid component reference occurs, Bascik presents a full-screen interactive error overlay directly in the browser:

• Source Line Remapping: Displays the original HTML template file, line number, and column.
• Detailed Stack Traces: Strips internal V8 and Node runtime frames to highlight your authored code.
• Auto-Dismiss on Fix: As soon as you correct the error and save the file, the dev server re-transpiles the page and dismisses the overlay instantly.

A typo in a build script, then the fix:

Automatic Watching & Invalidation

The development server watches:

• src/pages/: Adding or editing pages immediately creates or updates the corresponding route.
• src/components/ (and all directory.components roots): Editing a component automatically re-transpiles every page that uses that component tag.
• src/ (or scripts.importRoot): Updating shared @/ script helpers invalidates dependent build script caches and re-renders affected pages. A helper imported at request time by a src= server script or API route, at any depth, is reloaded on the next request together with every module that imports it; no restart and no edit to the importing file is needed. A helper imported by an inline data-bascik-server script is picked up when its page recompiles (or after a restart), because the inline module is a data: URL the module graph cannot record an importer edge for.
• pipeline.watchPaths: Custom content directories or JSON data files trigger re-compilation according to your configured globs.

Build Time of This Website

The numbers below are not typical. They describe this website's own production build (bascik --build), measured on one machine, because it is a large real site: many pages, many components, and build scripts that render Markdown, generate images, and write the search index. The Pages phase includes transpiling and scoping each page as well as its build-script work; it is not a component/CSS-only benchmark. The breakdown lists each build phase, and the per-page figures show the spread between a typical page and the slowest one.

The build runs your Node.js build scripts in isolated child processes, a few at a time, and caches each result. The first build pays for every script. After that, only scripts whose inputs changed run again. The page and component counts are counted live on every build. The timings come from a measured build and name the machine and date they were taken on.