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.
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.

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).

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.

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.