Any HTML goes inside as slot content.
Any HTML goes inside as slot content.
No content provided.
Card body text.
Card body text.
Main body content.
` elements, so raw code examples stay literal.
### Props
Inject text values into a component at usage time.
```html
Home
A practical heading
Markdown stays comfortable for authors, while the published page stays vanilla HTML.
Add an editorial treatment with ordinary CSS.
```
The parser emits ordinary HTML, so it can be styled by a global stylesheet or wrapped in a Bascik component. For reusable scoped styles, have the script emit `${marked(md)} ` and give that component a default slot.
Use wrapper descendant selectors for generated slot content:
```css
.markdown-content h2 { margin-block: 2.5rem 0.75rem; }
.markdown-content blockquote { border-left: 4px solid currentColor; }
```
Do not rely on a bare `h2 {}` component rule for Markdown passed through a slot. Bare element rules are transformed before slot content is inserted; a scoped wrapper selector continues to match the generated descendants.
### 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. Hardcoding those values in every page file works. However, a shared script is easier to maintain. You can change the logic once and every page picks it up automatically.
Bascik makes this possible by injecting three environment variables into every `data-bascik-build` subprocess: `BASCIK_PAGE_FILE`, `BASCIK_PAGES_DIR`, and `BASCIK_SITE_URL` (described in the Environment Variables table above).
#### Canonical URL Example
A canonical URL tag tells search engines which URL is the authoritative version of a page. Every docs page on this site uses a shared `scripts/canonical.ts` that derives the URL from `BASCIK_PAGE_FILE`:
```ts
// scripts/canonical.ts
export async function canonical(): Promise {
const siteUrl = (process.env.BASCIK_SITE_URL ?? '').replace(/\/$/, '');
const pageFile = process.env.BASCIK_PAGE_FILE ?? '';
const pagesDir = process.env.BASCIK_PAGES_DIR ?? '';
if (!siteUrl || !pageFile || !pagesDir) return '';
const relPath = pageFile.slice(pagesDir.length).replace(/^[\\/]/, '').replace(/\\/g, '/');
const withoutExt = relPath.replace(/\.html$/, '');
const route = withoutExt === 'index' ? '' : withoutExt.replace(/\/index$/, '/');
const urlPath = route ? `/${route}` : '/';
return ``;
}
```
Use it from any page's ``:
```html
```
#### Reading the Page's Own HTML
For richer outputs, including Open Graph tags or JSON-LD structured data, a script can also read the page file itself to extract metadata. `BASCIK_PAGE_FILE` is an absolute path, so `readFile` works directly:
```ts
// scripts/article-schema.ts (simplified)
import { readFile } from 'node:fs/promises';
export async function articleSchema(): Promise {
const pageFile = process.env.BASCIK_PAGE_FILE ?? '';
const siteUrl = (process.env.BASCIK_SITE_URL ?? '').replace(/\/$/, '');
if (!pageFile || !siteUrl) return '';
const html = await readFile(pageFile, 'utf8');
const titleMatch = html.match(/]*>([^<]+)<\/title>/);
const descMatch = html.match(/` and `` are always present as written.
### data-bascik-dev
Tag a browser script with `data-bascik-dev` to mark it as dev-only. In development the attribute is stripped and the script runs normally in the browser. In production builds (`bascik --build`) the entire script tag is removed.
```html
```
Useful for debug logging, development overlays, or any browser script that should never ship to production.
> **dev vs. build:** `data-bascik-build` executes at transpile time and injects HTML into the page. `data-bascik-dev` runs in the browser, but only in dev mode.
### data-bascik-server
Tag a `
```
`process.env.BASCIK_REQUEST` is a JSON string with four keys:
* `path`: URL path without query string, e.g. `"/about"`
* `method`: HTTP method in uppercase, e.g. `"GET"`
* `headers`: request headers as string-to-string object (HTTP/2 pseudo-headers excluded)
* `searchParams`: parsed query params as string-to-string object
Bascik intentionally does not inject a global `escapeHtml()` helper into every server script. If you want a shared escape utility, keep it in a project file or import it explicitly.
Rules:
* Top-level `import` and `await` are supported.
* `data-bascik-server` blocks are preserved through `bascik --build` and executed at request time when served with `bascik --serve` or the dev server.
* They are NOT executed during `bascik --build` itself.
* Scripts are NOT wrapped in an IIFE (they are Node.js code, not browser JS).
* On error, a warning is logged and the tag is replaced with an empty string.
---
## 9. Configuration (`bascik.config.ts`)
Use `bascik.config.ts` (preferred) or `bascik.config.js` (takes precedence if both exist). Import `defineConfig` for full editor autocomplete and inline docs:
```ts
// bascik.config.ts
import { defineConfig } from '@bascik/bascik/config';
export default defineConfig({
directory: {
pages: "src/pages", // default
components: "src/components", // default
},
watch: [], // re-transpile all pages when these paths change (dev only)
// exec: Optional array of custom build-lifecycle script objects { script: string, watch?: string[] }.
// Executed sequentially in array order before page transpilation during --build, and on startup/watched file changes in dev mode.
// Note: The commented examples below demonstrate possible custom build tasks (e.g. search indexes, RSS feeds, social card images).
// Do NOT add exec entries unless your project actually implements corresponding script files!
exec: [
// Example: { script: 'scripts/generate-search-index.ts', watch: ['content/'] },
// Example: { script: 'scripts/generate-sitemap.ts', watch: ['content/'] },
],
// Critical: custom lifecycle scripts registered in `exec` must write generated artifacts directly to your output directory (such as `dist/` or `dist/assets/`) rather than `src/` to prevent polluting your source tree or causing infinite watcher re-transpile loops.
scopeScriptBlocks: true,
inheritAttributes: true,
scopeAttribute: {
class: true,
id: true,
name: true,
},
deduplicateCss: true,
skipTranspilingElementContents: ['code'], // don't scope inside these elements
minify: {
html: false,
css: false,
js: false,
identifiers: false, // false in dev; true in --build and --serve
},
inlineStyles: false, // false | true | ['src/pages/css/styles.css']
cacheHttp: false, // dev default; automatically true in --serve mode
siteUrl: 'https://example.com',
generate: {
sitemap: true, // write dist/sitemap.xml
robots: true, // write dist/robots.txt
},
useWorkers: false, // true: transpile pages across CPU-core worker threads
buildScriptCache: true, // false: disable disk cache for
```
### petite-vue
petite-vue (~5 KB) is a Vue-compatible progressive enhancement library. Declare `v-scope` on any element to give it isolated reactive state:
```html
{{ count }}
```
Load it once in the page `` with `defer init` to auto-mount all `v-scope` elements:
```html
```
### Alpine.js
Alpine.js uses `x-data` for state and `@click` / `x-show` for events and visibility:
```html
Hidden content.
```
### Tailwind CSS
Tailwind utility classes are global by design. Bascik's class scoping would rename `class="flex gap-4"` to `class="bascik__comp__flex bascik__comp__gap-4"`, breaking Tailwind's CSS.
**Required config:** disable class scoping in `bascik.config.ts`:
```ts
export default {
scopeAttribute: {
class: false, // let Tailwind utility classes pass through unchanged
id: true,
name: true,
},
};
```
Include Tailwind via CDN (development) or Tailwind CLI (production):
```html
```
With `class: false`, utility classes work normally inside any component:
```html
```
Trade-off: with `class: false`, Bascik no longer isolates component class names. IDs and names remain scoped independently.
### HTMX, Stimulus, and Others
* **HTMX:** Uses `hx-get`, `hx-post` attributes for server-driven partial updates.
* **Stimulus:** Uses `data-controller` for attaching behavior to DOM structures.
* **Chart.js, D3, Leaflet:** Mounts to elements via `getElementById`; Bascik rewrites the ID and matching selectors at build-time so they stay in sync.
---
## 13. Testing
Bascik provides per-package commands and workspace-wide aggregators run from the root.
### Monorepo Aggregators
```sh
yarn typecheck:all # typecheck pkg, create, docs, ext
yarn check:all # spelling and web standards
yarn unit:all # unit tests across all packages
yarn e2e:all # Playwright E2E suites across all packages
yarn coverage:all # update coverage across all packages
yarn test:all # typecheck:all + check:all + unit:all + e2e:all + docs:lighthouse
```
### Unit Tests (Vitest)
```sh
yarn pkg:unit # single run (@bascik/bascik)
yarn pkg:test # watch mode
yarn create:unit # create-bascik unit tests
yarn docs:unit # bascik-docs unit tests
yarn ext:unit # bascik-vscode unit tests
yarn pkg:bench # benchmarks
```
Each `pkg/src/lib/*.ts` module has a paired `*.test.ts`. Because modules depend on `BascikConfig` (a singleton), unit tests use `vi.mock('../config.ts', ...)` to stub configuration, then import the module under test **after** the mock call.
### End-to-End Tests (Playwright)
```sh
yarn pkg:build # build package first
yarn pkg:e2e # run static production suite
yarn pkg:e2e:dev # run dev server live-reload and watch suite
yarn pkg:e2e:prod # run both HTTP/1.1 and HTTP/2 production server suites
yarn pkg:e2e:prod:http1 # run cleartext HTTP/1.1 prod server suite
yarn pkg:e2e:prod:http2 # run TLS HTTP/2 prod server suite
```
The E2E suite lives in `pkg/e2e/` and supports four execution modes:
1. **Static production suite (`playwright.config.ts`)**: builds the fixture site with `bascik --build` and serves static files via `server.ts` on port 4200.
2. **HTTP/1.1 production server suite (`playwright.server.config.ts`)**: boots cleartext `bascik --serve` over HTTP/1.1 on port 9443 to test `data-bascik-server` request-time script execution and cleartext server behavior.
3. **HTTP/2 production server suite (`playwright.server-http2.config.ts`)**: boots TLS-enabled `bascik --serve` over HTTP/2 on port 9444 to test `data-bascik-server` request-time script execution and encrypted server behavior.
4. **Dev server watch suite (`playwright.dev.config.ts`)**: boots `bascik --dev` on port 8080 to run the full test suite and live-reload watcher tests directly against the live dev server with SSE tracking and open-page priority re-transpilation.
The fixture config sets `minify.identifiers: false` so Playwright selectors can use readable scoped names like `bascik__my-comp__btn` instead of opaque hashes. However, in production builds (where `minify.identifiers: true` is enabled), Bascik compiles and minifies element IDs and class names. Consequently, relying on raw CSS selectors like `page.locator('.my-class')` or `page.locator('#my-id')` will fail because those identifiers are hashed and compressed.
To handle this, keep a clear distinction between compiler testing and application testing:
* **Compiler-Level E2E Tests (`pkg/e2e/`):** These verify that Bascik's scoping and transpilation systems work. They deliberately target exact compiled class names (e.g., `.bascik__my-comp__wrapper`) and rewritten IDs (e.g., `[id$="__btn"]`). Do not use generic `data-testid` attributes for these, as doing so would bypass verifying the actual compilation engine.
* **Application-Level E2E Tests (`docs/e2e/`):** These verify user-facing behavior of application widgets. To make them resilient to identifier minification and hashing, use standard `data-testid` attributes (e.g., `data-testid="search-input"`) with Playwright's native `page.getByTestId(...)` locator, or native accessibility-based locators like `page.getByRole(...)` and `page.getByPlaceholder(...)`.
**Adding a new e2e test:**
1. Add a component in `pkg/e2e/src/components/my-feature/`
2. Add a page in `pkg/e2e/src/pages/my-feature-test.html` with two or more instances (to verify isolation)
3. Add `pkg/e2e/tests/my-feature.test.ts` using the standard pattern:
```ts
import { test, expect } from '@playwright/test';
test.describe('my-feature-test page', () => {
test.beforeEach(async ({ page }) => { await page.goto('/my-feature-test'); });
test('instances are isolated', async ({ page }) => {
const a = page.locator('.bascik__my-feature__wrapper').nth(0);
const b = page.locator('.bascik__my-feature__wrapper').nth(1);
// assert A and B are independent
});
});
```
There are 44 e2e test files covering CSS scoping, JS scoping, slots, props, attribute inheritance, animations, observers, SVG, and head components.
### Debugging with VS Code and Node.js
Bascik works smoothly with debuggers because it operates directly on vanilla HTML, CSS, and JavaScript without complex runtime abstractions or heavy bundle transformations.
#### Source Location Preservation
Debugging server-side scripts, build-time scripts, and browser component code in Bascik requires no special source map plugins or transpilation step:
* **Server and Build Scripts:** Bascik automatically appends `//# sourceURL=${relPath}` comments to temporary script modules created during compilation (`