Start Here

Getting Started

Bascik requires Node.js v24+. Get up and running in under five minutes.

Quick Start

The fastest way to start a new Bascik project:

npm create bascik@latest

Enter a project name when prompted (or press Enter for bascik-app). The tool then asks two questions:

Install dependencies now?: select Y to run npm install immediately
Start the dev server after install?: select Y to launch the dev server right away

Select Y for both and you're live at https://localhost:8443 with no further commands needed.

npm create bascik@latest scaffolds a complete starter site: pages, components, global CSS, bascik.config.js, and a .gitignore. If you prefer to set everything up manually, see Manual Setup below.

Starting the Dev Server

Run npm run dev (or yarn dev) to start the development server. Bascik serves your site over HTTP/2 at https://localhost:8443 by default (the port auto-increments if 8443 is busy). It transpiles your pages, watches for changes, and live-reloads the browser on every save.

SSL certificates are generated automatically on first run. Install mkcert for a trusted cert with no browser warning:

# macOS
brew install mkcert
mkcert -install   # only needed once per machine

After running mkcert -install, restart the dev server. See the CLI page for more details on SSL certificate setup and browser-specific gotchas.

Folder Structure

Bascik looks for two directories by default. Both can be overridden in bascik.config.js.

text

src/
  components/  ← component .html and .css files
  pages/       ← one .html file per route

Manual Setup

For an existing project, install Bascik with your preferred package manager:

npm install @bascik/bascik
# or
yarn add @bascik/bascik
# or
pnpm add @bascik/bascik

Run bascik init in your project directory to scaffold the starter files and folder structure automatically. If you prefer to wire things up yourself, add the following to your package.json:

json

{
  "type": "module",
  "scripts": {
    "dev": "bascik",
    "build": "bascik --build"
  }
}

<!-- demo:component-html -->
```html
<nav class="nav">
  <a href="/">Home</a>
  <a href="/about">About</a>
</nav>

html

<!DOCTYPE html>
<html>
<head><title>Home</title></head>
<body>
  <site-nav></site-nav>
  <h1>Hello world</h1>
</body>
</html>

Your First Component

Create the component file

The file name becomes the tag name.

htmlsrc/components/site-nav.html

<nav class="nav">
  <a href="/">Home</a>
  <a href="/about">About</a>
</nav>

Reference it in a page

No imports or registration. Just use the tag.

htmlsrc/pages/index.html

<!DOCTYPE html>
<html>
<head><title>Home</title></head>
<body>
  <site-nav></site-nav>
  <h1>Hello world</h1>
</body>
</html>

Start the dev server

yarn dev

The server runs on https://localhost:8443 and live-reloads on every change.

Build for production

yarn build

Output is written to the dist/ directory. Deploy it anywhere that serves static files.

Next: Add scoped CSS to your component by creating src/components/site-nav.css alongside your HTML file. See Scoped Styles →

What to Read Next

Once your first page is running, the next docs pages map cleanly to the next questions people usually have:

CLI / Command Line: command output, watch behavior, --check, and production preview commands
Configuration: every bascik.config.js option in one place
Scoped Styles: how paired .css files and inline <style> tags are isolated per component

A Small First Habit

Open the compiled file in dist/ after your first build. It is the fastest way to verify what Bascik actually emitted:

component tags should be replaced with plain HTML
scoped class names should be present where component CSS applies
build-script output should already be inlined into the page

When you need the detailed terminal output for dev mode, build mode, static checks, or file watching, use the CLI page. Keeping that output reference in one place makes the Getting Started guide easier to skim.