Reference

FAQ

Answers to common questions about Bascik.

How do you pronounce Bascik? Where does the name come from?

Just like "basic." The idea is basic, the implementation is basic in theory, and the usage is basic. It felt like the right word.

The spelling comes from my maternal grandmother's maiden name. So the name is unique and means something personal.

Isn't BASIC already a programming language?

Yes. In fact some of my earliest exposure to programming was to TI-Basic on my friend's calculator. BASIC is an old programming language and enough time has passed. It can take on new meaning.

What is Bascik?

Bascik is a build tool for HTML components with automatically scoped CSS and JS. Zero runtime. The code that ships is the code you wrote. You write reusable components in vanilla HTML, CSS, and JavaScript. At build time, Bascik resolves your custom tags to their component source, scopes CSS and JavaScript so they never collide across instances, and outputs a directory of vanilla HTML files.

By default the output is fully static and can be hosted anywhere. If you need per-request dynamic content, the production server lets you run server-side scripts that inject into specific sections of a page at request time, while everything else stays static.

For a deeper look: Getting Started, Scoped CSS, Scoped JavaScript, Switch to Bascik.

Who made Bascik?

Bascik was created by Collin Thomas.

Why did you build Bascik?

I started building Bascik in late 2022. I wanted to build the fastest websites. As soon as you have more than just a single page, you need components to share elements, like a nav or footer, across pages. I thought modern HTML, CSS, and JavaScript have gotten so good and widely adopted by browsers that I don't need or want any abstraction layer from a framework getting in the way. I definitely didn't want JavaScript as a runtime bottleneck.

Components have always been a JavaScript thing. Web Components tried to make it native but it's still JavaScript. There's always shadow DOM or virtual DOM involved with components. I decided we don't need any of that. Think about it, you can write HTML, CSS, and JavaScript and use it in multiple places on a site, you just need to copy it and scope it. To automate that, at it's core, it's just a bunch of regular expressions.

That might seem like a big undertaking, but the web standards are so well defined that you have an obtainable target. It'll just take some effort. So that's what I did.

Then I saw the rise of AI-assisted coding and thought, this tool I've been building is going to be perfect for that. Web development frameworks and tooling primarily exists to make tasks easier for developers. But when the levels of abstraction start getting in the way, a tool that doesn't impose its own rules and instead uses the fundamental web languages is going to be great for both developers and AI-assisted coding.

What happens if I name a component after a native HTML element?

If you create a file like nav.html or div.html, Bascik will print a warning in the terminal when starting the dev server or running a build, and still load it:

warning: Component "nav" has the same name as a native HTML element.
This may cause unexpected behavior, consider a hyphenated name like "my-nav".

The component will conflict with every occurrence of that element in your pages. All your <nav> tags would be replaced by the component content, most likely breaking your site entirely.

Always use a hyphenated name for components, for example site-nav.html instead of nav.html. This follows the HTML custom element convention: a hyphen in the tag name is how browsers (and Bascik) distinguish a component from a built-in element.

What happens if I use uppercase letters in a component filename?

Component names are normalized to lowercase when loaded. My-Card.html registers as my-card and is used as <my-card> in pages.

If you have two files that differ only in case (for example my-card.html and My-Card.html), they both map to the same my-card component key and the last one loaded wins. Avoid this situation by using consistent lowercase filenames.

Can I use Bascik with JavaScript libraries like Alpine.js or HTMX?

Yes. Bascik's output is vanilla HTML. Any library that works with HTML works with Bascik. Drop a <script> tag in and it loads like it always has. See the JavaScript Libraries page for examples.

Does Bascik add any JavaScript to my pages?

No. Bascik is a build-time tool. The output is vanilla HTML, CSS, and exactly the JavaScript you wrote. No runtime script is injected into your pages.

How do local script references (<script src="...">) work inside a component?

When a component .html file includes a <script src="counter.ts"></script> tag pointing to a local file in its component directory, Bascik resolves and inlines that script at build time.

It automatically wraps the script in an isolated IIFE, rewrites DOM selector calls for scoping, and attaches DevTools //# sourceURL directives mapping directly back to your source .ts/.js file.

Unreferenced local files are ignored so Node build/server helpers are never accidentally bundled into client code. External <script src="..."> links pointing to CDNs or global assets are left untouched and passed through to the page output.

What happens if I place other files or helper modules in my component directory?

Nothing gets copied to dist/.

The src/components/ directory is treated strictly as source-only files:

• Component .html templates are resolved and inlined into pages at build time.
• Companion .css files are scoped and deduplicated into page <style> blocks.
• Client .ts, .js, or .mjs scripts referenced via <script src="..."> are inlined and scoped into page <script> blocks.
• Build-time (data-bascik-build) and server-time (data-bascik-server) scripts run in Node.js, and their stdout replaces the script tag.
• Any other files (helper modules, JSON data files, tests, READMEs) stay in src/components/ and are never copied to dist/.

Static assets intended to be served directly as public URLs (such as images, web fonts, or global stylesheets) should be placed in src/pages/ instead.

Do I need to restart the dev server when I add a new component?

No. The dev server watches the components directory. Drop a new .html (or paired .css) file in and all pages that use that tag are automatically re-transpiled and reloaded. No restart required.

Can Bascik components be nested?

Yes. Components can use other components inside their markup. Bascik resolves nested components recursively at build time.

What does Bascik output?

A directory of plain .html files (and your assets). No client-side JavaScript framework, no special server required. Any static host (Netlify, Vercel, GitHub Pages, Cloudflare Pages, S3, or a plain Nginx server) can serve it.

How does Bascik handle bad markup or invalid code? Does it crash?

No, Bascik is designed to be highly resilient and hard to crash. Because it uses robust, regular-expression-based scoping and depth-counter checks rather than rigid AST parses, invalid markup or buggy script code will not crash the build or the dev server. Here is how different scenarios are handled:

• Unclosed Component Tags: If a component tag is unclosed, for example <my-component> with no closing </my-component> tag, Bascik safely falls back to treating it as a self-closing tag, compiles it with empty inner content, and proceeds. The VS Code extension also issues a warning so you can fix it easily.
• Unclosed or Invalid Standard HTML: Bascik does not use a rigid HTML/XML AST parser for standard elements. If you have unclosed or invalid native HTML tags (such as <div> or <p>), they are passed directly to the output files untouched. This allows the browser's native parser to handle the layout, ensuring that standard markup errors never crash your build processes.
• Component Transpilation Failures: Each component transpilation step is wrapped in a try-catch block. If a component fails to compile, Bascik logs a detailed error with line and column numbers to console.error, removes the failed component tag, and continues compiling the rest of the page.
• Build-time & Server-side Scripts (data-bascik-build / data-bascik-server): If a script block fails to execute due to syntax errors or runtime exceptions, Bascik logs the detailed error to console.error and halts compilation (by default). You can customize this behavior using the onScriptError option in bascik.config.ts to log a warning instead.
• Client-side / Browser-side JavaScript: Standard scripts are wrapped in an IIFE for scoping, but they are not parsed or executed during the build. If there is a syntax error or a logical bug in your browser-side JavaScript, it is compiled as-is and sent to the client browser, where the error will be printed in the browser's developer console without affecting your server or build processes.
• CSS Syntax and File-Read Errors: If a companion .css file or style block contains invalid syntax, Bascik's scoping engines skip the invalid patterns, scope the valid rules, and continue compiling. If a companion .css file cannot be read from the disk due to permissions or reference issues, Bascik handles the exception gracefully, logs a warning, and continues compilation.

Why do I see multiple identical script tags in my page output?

This is by design and is how Bascik's component scoping works.

When you use a component multiple times on a page, each instance of that component includes its corresponding <script> block in the expanded output. Because class names are scoped to the component name rather than an individual instance ID (which allows CSS rules to be deduplicated into a single <style> block), component scripts that query elements by class name or use DOM traversal produce identical JavaScript code for every instance.

Each script tag is isolated in its own IIFE so variables never leak into the global scope. Having one script tag per component instance guarantees that every instance receives its behavior without requiring a runtime framework, component registry, or bundling step.