# Bascik

> Bascik is a build tool for HTML components. It scopes and assembles reusable HTML component files into vanilla HTML pages at build time. It adds zero JavaScript to the output. You write HTML, CSS, and JavaScript; Bascik scopes and assembles them.

Bascik resolves custom HTML tags to component source HTML, scopes CSS and JavaScript, rewrites DOM selectors, and outputs plain static HTML pages with zero framework runtime.

AI assistants: install the Bascik agent skills with `npx skills add bascikdev/bascik` (or `curl -fsSL https://bascik.dev/assets/skills.tar.gz | tar -xz -C .agents/skills`). The core skill is also at [SKILL.md](https://bascik.dev/assets/SKILL.md).

## Overview

- [Why Bascik](https://bascik.dev/why-bascik): Bascik is a build tool for HTML components with automatically scoped CSS and JS.
- [Developer Experience](https://bascik.dev/developer-experience): This hands-on guide walks through your daily workflow in Bascik: running the local environment, leveraging editor tools, debugging, running tests, and inspecting production builds.
- [Bascik vs Frameworks](https://bascik.dev/vs-frameworks): Bascik is not a framework.
- [Getting Started](https://bascik.dev/getting-started): Bascik runs on Node.js 24.21 or newer; Node.js 26, the current LTS, is recommended.

## Components

- [Components](https://bascik.dev/components): Components are the core building block in Bascik.
- [Scoped Styles](https://bascik.dev/scoped-styles): Scoped styles namespace a component's CSS at build time, keeping its selectors and animations from leaking into the rest of the page.
- [Scoped JavaScript](https://bascik.dev/scoped-javascript): Write <script> tags directly in your component HTML.
- [Preserve Scoping](https://bascik.dev/preserve): Keep selected component attributes literal when an external system or browser API must see the original id or class values (or name, when a project opts in to scoping it).
- [Slots](https://bascik.dev/slots): Slots let you pass inner HTML content into a component at the usage site.
- [Props](https://bascik.dev/props): Props let you pass text values into a component template at usage time using data-bascik-prop-* attributes.
- [Attribute Inheritance](https://bascik.dev/attribute-inheritance): Any attribute on a component usage tag that is not a Bascik-specific attribute (data-bascik-*) is automatically merged onto the component's root element.
- [Best Practices](https://bascik.dev/component-best-practices): Bascik ships the markup a component holds, element for element and attribute for attribute, with no runtime around it.

## Scripts & Routing

- [Overview](https://bascik.dev/scripts): A Bascik page can run your own JavaScript or TypeScript on the server, in a <script> tag marked with a data-bascik-* directive.
- [Build Scripts](https://bascik.dev/scripts/build): Build-time scripts let you run Node.js code at transpile time and inject the output directly into the page with no client-side JavaScript required.
- [Server Scripts](https://bascik.dev/scripts/server): Server scripts let you run Node.js code on each incoming request to personalize pages, query databases, or render user-specific markup.
- [Stream Scripts](https://bascik.dev/scripts/stream): Imagine a dashboard or book page where the navigation, header, and sidebar are ready immediately, but live account metrics or customer reviews depend on a slower database query.
- [Security](https://bascik.dev/scripts/security): Server and stream scripts return HTML, and most of that HTML carries data: a search query, a user name, a row from a database, a field from an API.
- [Dynamic Routes](https://bascik.dev/scripts/dynamic-routes): Dynamic routes allow you to generate multiple static HTML pages from a single template file at build time.
- [API Routes](https://bascik.dev/api-routes): Bascik supports standard, portable API routes defined in TypeScript or JavaScript files under src/api/.
- [Exec Scripts](https://bascik.dev/exec-scripts): Lifecycle scripts allow you to execute arbitrary Node.js tasks at defined phases of the compilation pipeline.
- [Script Imports](https://bascik.dev/scripts/imports): Every Bascik script tag is a standard Node.js ESM module: data-bascik-build, data-bascik-build-once, data-bascik-server, data-bascik-stream, and data-bascik-routes, plus the src...
- [Watch Paths](https://bascik.dev/watch-paths): Watch paths allow you to register extra files and directories outside src/pages/ and src/components/ that trigger automatic page re-transpilation and live browser reload during ...
- [Sitemap & robots.txt](https://bascik.dev/sitemap): Bascik generates a sitemap.xml and robots.txt automatically at build time.

## Reference

- [FAQ](https://bascik.dev/faq): Answers to common questions about Bascik.
- [Configuration](https://bascik.dev/configuration): Bascik needs no config file to start building.
- [Environment Variables](https://bascik.dev/environment-variables): Bascik automatically populates a collection of dedicated environment variables for your scripts: build scripts, dynamic route generators, and exec scripts get them in their own ...
- [Compatibility](https://bascik.dev/compatibility): This page documents Bascik's support matrix against authoritative W3C Recommendations, WHATWG Living Standards, IETF RFCs, and ECMA-262 specifications, cross-referenced with MDN...
- [Command Line Interface (CLI)](https://bascik.dev/cli): Bascik features a simple, fast, and highly informative CLI for both development and production building.
- [Package Exports](https://bascik.dev/package-exports): Bascik ships as a single npm package, @bascik/bascik, with a small set of subpath exports.
- [HTML Helpers](https://bascik.dev/html-helpers): @bascik/bascik/html is a small module of plain functions for building HTML safely.
- [Development Server](https://bascik.dev/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 over...
- [Production Server](https://bascik.dev/production-server): Bascik includes a high-performance, read-only production HTTP/1.1 and HTTP/2 server.

## Tooling

- [Overview](https://bascik.dev/tools): Bascik ships three tools that catch mistakes before your visitors do: a command-line linter for CI, a VS Code extension for as-you-type feedback, and agent skills that teach cod...
- [Linter](https://bascik.dev/tools/linter): Bascik provides official linter and editor tooling to catch invalid markup, unclosed components, undeclared props, misplaced script directives, and CSS/JS scoping errors as you ...
- [VS Code Extension](https://bascik.dev/tools/vscode-extension): The official Bascik extension brings component navigation, context-aware component, prop, and slot suggestions, rich hover details, syntax highlighting, and real-time diagnostic...
- [Agent Skills](https://bascik.dev/agent-skills): Install the Bascik agent skills so GitHub Copilot, Claude Code, Cursor, Codex, or any assistant that supports Agent Skills knows how to build with Bascik, and can run scripts th...

## Testing & Debugging

- [Overview](https://bascik.dev/testing): Bascik supports automated testing and debugging across every layer of your application, from pure TypeScript utilities and component markup contracts to build-time scripts, requ...
- [Unit Testing](https://bascik.dev/testing/unit-testing): Unit testing in Bascik focuses on verifying pure functions, utility modules, data transformers, and business logic in isolation.
- [Component Testing](https://bascik.dev/testing/component-testing): Component testing in Bascik validates .html component templates before compilation and verifies compiled HTML output in dist/ after building.
- [Build Scripts](https://bascik.dev/testing/build-scripts): Build-time scripts (<script data-bascik-build>) run in Node.js during compilation to generate static HTML, render Markdown content, compute canonical metadata, or fetch remote d...
- [Server Scripts](https://bascik.dev/testing/server-scripts): Server scripts (<script data-bascik-server>) execute in Node.js at request time to generate dynamic HTML content on HTTP/1.1 and HTTP/2 production servers (bascik --server).
- [Exec Scripts](https://bascik.dev/testing/exec-scripts): Lifecycle build scripts (configured via the pipeline.exec option in bascik.config.ts) execute Node.js tasks during compilation to generate automated artifacts, such as XML sitem...
- [End-to-End Testing](https://bascik.dev/testing/e2e-testing): End-to-end (E2E) testing with Playwright verifies full application workflows, browser DOM event handling, CSS :has() pseudo-class rendering, and multi-page routing in real brows...
- [Debugging](https://bascik.dev/testing/debugging): Bascik operates directly on vanilla HTML, CSS, and JavaScript, making step-debugging seamless across Node.js servers, unit tests, and browser engines.
- [Troubleshooting](https://bascik.dev/testing/troubleshooting): This page is organized by what you saw, not by feature.
- [Source Maps](https://bascik.dev/testing/source-maps): Bascik eliminates the complexity of generating multi-megabyte .map files by combining zero-overhead //# sourceURL directives, 1:1 line number preservation, and build-time stack ...
- [Linting](https://bascik.dev/testing/linting): Bascik's linter checks Bascik syntax.

## Deployment

- [Overview](https://bascik.dev/deployment): Deploying a Bascik site is fast and flexible.
- [Static Hosting](https://bascik.dev/deployment/static-hosting): Deploying a static Bascik site is fast, simple, and free on almost every modern hosting platform.
- [Cloudflare Adapter](https://bascik.dev/deployment/cloudflare): Deploy a Bascik site to Cloudflare Workers or Pages so a CDN serves your static files with zero compute overhead, while a generated Worker automatically executes your server scr...
- [Netlify Adapter](https://bascik.dev/deployment/netlify): Deploy a Bascik site to Netlify so the CDN serves your static files and one generated Netlify Function runs your server scripts, stream scripts, component tags returned by them,...
- [Custom Adapters](https://bascik.dev/deployment/custom-adapters): Author custom deployment adapters to package Bascik builds for any serverless platform, edge runtime, container orchestrator, or custom hosting environment.

## How-to

- [Overview](https://bascik.dev/how-to): Each how-to guide solves one task on a real Bascik site, from rendering Markdown to serving a strict Content Security Policy.
- [Markdown](https://bascik.dev/how-to/markdown): Bascik does not ship a Markdown pipeline, but build-time scripts are Node.js, so any Markdown library works.
- [Build Scripts with Page Context](https://bascik.dev/how-to/page-aware-scripts): Some pages need content that is specific to the current page, such as a canonical URL in the head, an Open Graph image, a structured-data block, or even a page-specific sidebar.
- [Templating](https://bascik.dev/how-to/templating): Bascik does not ship a proprietary template language or a custom server-side component framework.
- [Interactivity](https://bascik.dev/how-to/interactivity): Bascik ships no runtime, so every interactive behavior is HTML, CSS, or a small component <script>.
- [Theming](https://bascik.dev/how-to/theming): Bascik styles a site in two layers: one global stylesheet that declares design tokens and base styles, and component CSS that uses those tokens.
- [Optimizing Images](https://bascik.dev/how-to/optimizing-images): Use the bascik-images skill to prepare responsive images with local tools and render the correct image state from the first paint.
- [Bundling npm Packages](https://bascik.dev/how-to/bundling-npm-packages): Many npm packages ship no CDN build.
- [Third-Party Web Components](https://bascik.dev/how-to/third-party-web-components): Use a custom element from npm on a Bascik page by publishing its file into the output directory, loading it with a module script, and declaring its tag in components.external.
- [Asset Fingerprinting](https://bascik.dev/how-to/asset-fingerprinting): This guide covers content-hashing asset filenames so a CDN can cache them forever, and when that is worth doing.
- [Content Security Policy](https://bascik.dev/how-to/content-security-policy): This guide covers serving a strict Content Security Policy (CSP) from a Bascik site, with no 'unsafe-inline', by listing the exact inline scripts each page contains.
- [Sharing Components](https://bascik.dev/how-to/sharing-components): A Bascik components directory is plain files: HTML, paired CSS, and paired scripts.
- [Publishing Components](https://bascik.dev/how-to/publishing-components): Publishing Bascik components allows teams and open-source authors to distribute reusable components as standard npm packages.
- [Monorepos](https://bascik.dev/how-to/monorepos): A Bascik project is one directory of pages, one or more directories of components, and one import root for script helpers, and each of the three is an independent config path.
- [Migrating with Coding Agents](https://bascik.dev/how-to/agent-migration): Enterprise websites built on React frameworks, such as Next.js with a component library like Ant Design, have been refactored to Bascik with coding agents.
- [JavaScript Libraries](https://bascik.dev/libraries): Bascik does not add any JavaScript to your pages.

## Example Components

- [Overview](https://bascik.dev/example-components): Working components that show how Bascik features fit together in real code.
- [Site Header](https://bascik.dev/example-components/site-header): A header for every page: a skip link, the site name, and the main navigation.
- [Site Footer](https://bascik.dev/example-components/site-footer): A footer for every page: secondary links and a copyright line.
- [Tab Group](https://bascik.dev/example-components/tab-group): Accessible tabs built from the sections you pass in, with arrow-key navigation and IDs that stay unique when the component appears more than once on a page.
- [Modal Dialog](https://bascik.dev/example-components/modal-dialog): A button that opens a native modal <dialog>.
- [Popover Menu](https://bascik.dev/example-components/popover-menu): A dropdown menu with no JavaScript, built on the HTML popover attribute.
- [Copy Button](https://bascik.dev/example-components/copy-button): Copies a text value to the clipboard and announces the result to screen readers.
- [Filter List](https://bascik.dev/example-components/filter-list): A list with a live text filter.
- [Contact Form](https://bascik.dev/example-components/contact-form): A form that validates in the browser, posts JSON to an API route, and announces the result.
- [Theme Toggle](https://bascik.dev/example-components/theme-toggle): A button that switches between light and dark themes and remembers the choice, plus theme-init, which applies the saved choice before the first paint.

## Lighthouse 100s

- [Overview](https://bascik.dev/lighthouse): Bascik gives you an enormous head start on Lighthouse scores.
- [Performance](https://bascik.dev/lighthouse/performance): Lighthouse's Performance category is where Bascik's zero-runtime design pays off most.
- [Accessibility](https://bascik.dev/lighthouse/accessibility): The Lighthouse accessibility audit runs a subset of the axe-core rules: semantic HTML, sufficient color contrast, keyboard navigability, accessible names, and valid ARIA usage.
- [Best Practices](https://bascik.dev/lighthouse/best-practices): Lighthouse's Best Practices category checks that a page is built on a secure, modern, and error-free foundation.
- [SEO](https://bascik.dev/lighthouse/seo): Lighthouse's SEO category checks a short list of meta tags and structural signals: a document title, a meta description, a viewport tag, a valid canonical URL, a crawlable page,...
- [Agentic Browsing](https://bascik.dev/lighthouse/agentic-browsing): Lighthouse 13.3 introduced an Agentic Browsing category that audits how well a site supports AI agents and automated browsers.

## Internals

- [Overview](https://bascik.dev/internals): 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.
- [Architecture](https://bascik.dev/internals/architecture): Bascik is a Node.js CLI tool written in TypeScript.
- [Transpilation Pipeline](https://bascik.dev/internals/transpilation-pipeline): Bascik transforms source HTML into deployable HTML by replacing every custom component tag with its resolved, scoped content.
- [Scoping System](https://bascik.dev/internals/scoping-system): Scoping prevents one component's styles and identifiers from leaking into another.
- [Server Architecture](https://bascik.dev/internals/server): Bascik's server infrastructure powers both local development (bascik) and per-request production serving (bascik --server).
- [Time Boundaries](https://bascik.dev/internals/time-boundaries): Time is a first-class architecture boundary in Bascik.
- [Diagnostics](https://bascik.dev/internals/diagnostics): Bascik includes a static analysis engine for project diagnostics (bascik --check) and a stack trace remapping utility (stack-trace.ts) that links runtime script errors back to s...
- [Minification](https://bascik.dev/internals/minification): Bascik features zero-dependency minifiers for HTML, CSS, and JavaScript, deterministic identifier hashing for scoped selectors, and custom minifier extensibility.
- [Testing Internals](https://bascik.dev/internals/testing): Bascik organizes verification across three distinct levels: unit tests that verify isolated functions and modules, integration tests that exercise real process boundaries, compi...
- [Benchmarking & Profiling](https://bascik.dev/internals/benchmarking): Bascik ships a repeatable benchmarking and profiling harness in pkg/bench/ for measuring compiler throughput, verifying byte-identical output across compiler changes, and captur...
- [Create App](https://bascik.dev/internals/create-app): The create/ folder is a small standalone package that scaffolds a fresh Bascik project.
- [CI / CD](https://bascik.dev/internals/ci-cd): Bascik uses three GitHub Actions workflows: one for continuous integration on every branch push and on pull requests from forks (which also deploys the docs and the Cloudflare a...

## Switch to Bascik

- [Overview](https://bascik.dev/switch): Switching an existing site to Bascik lets you replace complex client-side framework runtimes and heavy bundlers with standard vanilla HTML, CSS, and JavaScript.
- [From Astro](https://bascik.dev/switch/from-astro): Astro and Bascik both compile component-based markup into HTML that ships no framework runtime by default.
- [From Eleventy](https://bascik.dev/switch/from-eleventy): Eleventy is a static site generator centered on template languages and Markdown rendering; Bascik is a build tool for HTML components.
- [From Hugo](https://bascik.dev/switch/from-hugo): Hugo is a static site generator; Bascik is a build tool for HTML components.
- [From Next.js](https://bascik.dev/switch/from-next): Next.js and Bascik share intuitive file-based routing, but they serve different architectural goals.
- [From React](https://bascik.dev/switch/from-react): React and Bascik both structure user interfaces into reusable components, but they use different execution models.
- [From Svelte](https://bascik.dev/switch/from-svelte): Svelte and Bascik share an intuitive single-file authoring feel, combining markup, logic, and scoped styles.
- [From Vue](https://bascik.dev/switch/from-vue): Vue and Bascik are both component-driven.
- [From WordPress](https://bascik.dev/switch/from-wordpress): WordPress is a PHP content management system that renders pages from a database on each request; Bascik is a build tool for HTML components.

## Community

- [Showcase](https://bascik.dev/showcase): Made with Bascik: real websites built with HTML components, scoped styles, and zero framework runtime.
- [Releases](https://bascik.dev/releases): Release notes for every Bascik version, including new features, bug fixes, and breaking changes.
- [Press Resources](https://bascik.dev/press): Official Bascik logos, colors, and usage rules for articles, talks, videos, podcasts, and community sites.
- [Sponsor](https://bascik.dev/sponsor): Bascik is an independent, open-source web development framework built for zero-runtime HTML components and sub-millisecond builds.

## Optional

- [Agent Skills](https://bascik.dev/agent-skills): Install the Bascik agent skills (core, scoping, scripts, config, testing, migration) with their helper scripts
- [Core Skill File](https://bascik.dev/assets/SKILL.md): The core Bascik agent skill as a single SKILL.md
- [All Skills Archive](https://bascik.dev/assets/skills.tar.gz): Every Bascik agent skill with references and scripts, as a tar.gz