Start Here

Command Line Interface (CLI)

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

npm create bascik@latest: 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/
  bascik.config.js
  package.json
  .gitignore
  src/
    pages/
      index.html
      about.html
      contact.html
      404.html
      css/
        styles.css
    components/
      site-meta/
      site-header/
      site-footer/
      feat-card/
      my-counter/

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 https://localhost:8443 with no extra commands.

CLI reference

bascik          # dev: transpile, start HTTPS dev server, watch
bascik --build  # production: transpile to dist/ only
bascik --serve  # production server: serve a pre-built dist/ with HTTP/2
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, generates local TLS certificates if needed, starts the built-in HTTP/2 server, and begins watching for changes.

Typical output:

SSL: generated trusted certs via mkcert (run `mkcert -install` once if you haven't)

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

✓ 3 pages transpiled in 45ms
Server running at https://localhost:8443

If mkcert is not installed, Bascik falls back to a self-signed certificate:

SSL: self-signed cert generated (install mkcert for no browser warning)
transpiled: pages/index.html
✓ 1 page transpiled in 18ms
Server running at https://localhost:8443

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

Port 8443 is in use, trying 8444…
Server running at https://localhost:8444

Certs are generated once and reused on subsequent starts. Delete bascik-privkey.pem and bascik-cert.pem to regenerate them.

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.

Production server

bascik --serve starts the same HTTP/2 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 serve key in bascik.config.js to customize the server for both dev and production:

// bascik.config.js
export const bascikConfig = {
  serve: {
    port: 443,
    hostname: '0.0.0.0',   // bind all interfaces (needed in containers)
    keyFile: '/etc/ssl/site.key',
    certFile: '/etc/ssl/site.crt',
  },
};

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

To preview the production build with a 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