Reference

Command Line Interface (CLI)

Bascik features a simple, fast, and highly informative CLI for both development and production building.

Scaffold a new project

npm create bascik@latest
# or: npm create bascik@latest my-project

Scaffolds a complete starter project in a new directory. Prompts for a project name if not passed as an argument. Creates:

my-project/
  package.json
  bascik.config.ts
  vite.config.js
  .gitignore
  .vscode/
    launch.json
  .github/skills/bascik/SKILL.md
  .claude/skills/bascik/SKILL.md
  e2e/
    playwright.config.ts
    app.spec.ts
  src/
    pages/
      favicon.ico
      assets/
        favicon-32x32.png
        favicon.svg
        apple-touch-icon.png
      css/
        styles.css
      index.html
      about.html
      contact.html
      404.html
    components/
      site-meta/
        site-meta.html
        site-meta.test.ts
      site-header/
        site-header.html
        site-header.test.ts
      site-footer/
        site-footer.html
        site-footer.test.ts
      feat-card/
        feat-card.html
        feat-card.test.ts
      my-counter/
        my-counter.html
        my-counter.test.ts

Every scaffolded project includes co-located unit tests for its components, Playwright E2E browser tests in e2e/, Vitest configuration in vite.config.js, and pre-configured test scripts (npm test, npm run test:watch, npm run test:coverage, and npm run e2e).

After scaffolding, the tool prompts you interactively:

✓ Scaffolded my-project/

Install dependencies now? (Y/n)
Start the dev server after install? (Y/n)

Select Y for both and you're live at http://localhost:8080 with no extra commands.

CLI reference

bascik          # dev: transpile, start plaintext HTTP dev server, watch
bascik --build  # production: transpile to dist/ only
bascik --serve  # production server: serve a pre-built dist/ with HTTP
bascik --check  # static analysis: validate pages and components without building
bascik --build --log [path]  # optional build log; defaults to .bascik/build.log

Build logs

Use --log when you want a captured copy of the build output for debugging or CI investigation. The default path is .bascik/build.log, and you can override it with any custom path:

bascik --build --log
bascik --build --log ./logs/build.log

The terminal output still stays as the primary log, and the file is an optional diagnostic artifact. If you do not pass --log, Bascik does not create a build log file.

Starting the dev server

When you run bascik, Bascik transpiles your pages, starts the built-in HTTP server, and begins watching for changes. By default, it runs over unencrypted plaintext HTTP on port 8080 for zero-friction setup.

Typical output:

transpiled: pages/getting-started.html
transpiled: pages/index.html
transpiled: pages/about.html

✓ 3 pages transpiled in 45ms
Server running at http://localhost:8080

If port 8080 is already in use, Bascik automatically tries the next available port:

Port 8080 is in use, trying 8081…
Server running at http://localhost:8081

If you explicitly configure the server to run with TLS (enableTls: true in bascik.config.ts), Bascik will serve over HTTPS (default port 8443) and generate local TLS certificates if needed via mkcert or openssl fallback.

Watching for file changes

While the dev server is active, Bascik incrementally updates your build as files are added, updated, or removed.

• Modifying or adding pages rebuilds just that page:
  terminal

  transpiled: pages/about.html

• Modifying components rebuilds only the pages that use that component:
  terminal

  transpiled: pages/index.html
  transpiled: pages/about.html

• Static assets are copied into dist/:
  terminal

  copied: pages/css/custom.css

• Deleting pages removes the compiled output:
  terminal

  deleted file: pages/old-page.html

Transpilation and build errors

If you introduce a syntax mistake or a build-script error, Bascik logs the file and location without crashing the dev server.

Component transpilation failure:

[bascik] Transpilation failed for component <site-nav> during css-scoping in "pages/about.html" at (line 22, column 8)
  Defined in component template: "components/site-nav/site-nav.html"
  Error: ParseError: CSS Selector is invalid or could not be parsed.

Build script failure:

[bascik] build script error in "pages/index.html" at (line 12, column 5):
ReferenceError: marked is not defined

Unknown component tag:

[bascik] Unresolved component tag in "pages/about.html": <my-mistyped> - no matching component file found. Run `bascik --check` for a full report.

Custom 404 Page

Create a 404.html file in your pages directory (e.g. src/pages/404.html) and the dev server will automatically serve it as a fallback for any non-existent route with a 404 status code.

When you build for production (bascik --build), this file is compiled to dist/404.html, which is the standard location recognized by most static hosting providers (GitHub Pages, Netlify, Vercel, Cloudflare Pages) to serve custom 404 pages.

Static analysis with bascik --check

Run bascik --check from your project root to validate all pages and component files without starting the dev server or writing any output files:

bascik --check

It reports:

• Errors: hyphenated tags that have no matching component file
• Warnings: component files that exist but are never referenced
• Success: exits with code 0 when no errors are found

Example output:

[bascik check] ✓ 8 pages and 12 components checked - no errors

bascik --check exits with code 1 when errors are found, which makes it suitable for CI:

bascik --check && bascik --build

bascik --check does not validate CSS or JavaScript syntax. Use those tools immediately around it rather than treating them as a separate, later concern:

For most teams, the most useful CI command sequence is:

npx stylelint "src/**/*.css" && bascik --check && bascik --build

Production builds

Run bascik --build to write deployment-ready files to dist/:

bascik --build

The output uses root-relative asset paths (for example /css/styles.css) and must be served by an HTTP server. Opening files directly with file:// will break stylesheet and script loading.

For guidance on deploying to static hosts or running the production server, see Deploying.

Production server

bascik --serve starts the same HTTP server used for development, but pointed at a pre-built dist/ directory. Run --build first, then --serve:

bascik --build && bascik --serve

The production server:

• Serves pre-compiled pages from dist/ without watching for source changes.
• Has no live-reload SSE endpoint.
• Executes data-bascik-server script blocks on every request, just like the dev server.

Configuring the server

Use the prodServer key in bascik.config.ts to customize the server for both dev and production:

// bascik.config.ts
export default {
  prodServer: {
    port: 8080,
    hostname: '0.0.0.0',   // bind all interfaces (needed in containers)
    enableTls: false,      // set to true to run over encrypted HTTP/2 (HTTPS)
  },
};

When enableTls is true and keyFile / certFile are omitted, Bascik generates certificates automatically using mkcert (if installed) or openssl as a fallback.

To preview the production build locally with Bascik's built-in production server:

bascik --serve

Or with any third-party HTTP server:

npx http-server dist

Then open the URL printed by http-server (default: http://127.0.0.1:8080).

Editor setup and output inspection

VS Code false positives. Editors validate multiple <script> blocks in an HTML file as if they shared one scope. Bascik wraps each component script block in an IIFE at build time, so those editor warnings can be misleading. In VS Code, disable the project-level script validation:

{
  "html.validate.scripts": false
}

Inspect dist/ directly. Both the dev server and bascik --build write compiled HTML to dist/ on disk. This is the fastest way to confirm what Bascik emitted:

• custom component tags should be gone
• scoped class names should be present where component CSS applies
• the page <head> should contain injected styles
• build-script output should already be inlined