Documentation / Getting started

Getting started#

Install Blitsen, open a built web application in a native window, check compatibility and export a desktop executable.

Blitsen is pre-alpha and implements a subset of the web platform. Use doctor before every release and test the result on every operating system you plan to support.

Prerequisites#

Install Bun 1.3.14 or newer for development and building. The npm CLI entrypoint forwards to Bun on PATH. Node.js 20.11.0 or newer can install the package and run external blitsen/test drivers. Exported applications include Bun and do not require Node or Bun to be installed.

The platform package supplies a prebuilt native addon; installation does not compile Rust. Application code can import node:fs/promises, bun:sqlite and other Bun-supported builtins. Keep those imports external in browser-oriented bundlers; see Bun migration.

Blitsen accepts static web output with an index.html. If your project uses TypeScript, JSX, Vue, Svelte or bare npm imports, keep using its existing build tool. Blitsen consumes the directory that tool produces.

Install Blitsen#

Install the CLI globally so the blitsen command is available from any project:

npm install -g blitsen

If application code imports blitsen/* native modules or types, install the package in that project too. A local exact version is also useful when a team or CI must reproduce the same toolchain:

npm install -D --save-exact blitsen

Package scripts automatically prefer that local executable. The same installations work through another package manager's equivalents.

Try a plain HTML application#

Create a directory containing index.html:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Hello</title>
    <style>
      body { display: grid; min-height: 100vh; place-items: center; margin: 0; }
    </style>
  </head>
  <body>
    <button id="hello">Say hello</button>
    <script>
      document.querySelector("#hello").addEventListener("click", (event) => {
        event.currentTarget.textContent = "Hello from Blitsen";
      });
    </script>
  </body>
</html>

Open the directory in a native window:

blitsen .

Use --width, --height and --title to change the development window:

blitsen . --width 1024 --height 720 --title "Hello"

Add Blitsen to an existing project#

Add a blitsen object to package.json. The build command can be any command that writes static output; output is that directory, relative to package.json.

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "native": "blitsen build"
  },
  "blitsen": {
    "build": "vite build",
    "output": "dist",
    "name": "My App"
  }
}

Run Blitsen without a directory to execute the configured build and open its output:

blitsen

Passing a directory bypasses the configured build command:

npm run build
blitsen dist

See Configuration for every supported key.

Use your development server#

Start your usual server, then point Blitsen at it:

npm run dev
blitsen http://localhost:5173

The server continues to transform source and provide hot reload. Blitsen supplies the window and runtime. A local-directory run watches built files too: CSS changes are swapped when possible and other changes reload the document.

Inline and external source maps are applied to uncaught runtime diagnostics. See Develop with hot reload for the workflow and the diagnostic boundary.

Check the built output#

Run doctor against static output, not source code or a development-server URL:

npm run build
blitsen doctor dist

Errors identify output that cannot survive in the current runtime and block export. Warnings name unsupported or narrower behavior that needs review. A warning can still represent a real failure if your application calls the reported API without a fallback.

For CI or other tools, request JSON:

blitsen doctor dist --json

Export a desktop application#

With the configuration above:

npm run native

Or build a directory directly:

blitsen build dist --name "My App" --out MyApp

Embedded assets are the default, so the result is one executable. Run that artifact on the target platform and exercise the complete application before distributing it.

Next steps#

• Read Core concepts before adapting a browser application.
• Use Recipes for assets, routing, native modules and persistent data.
• Read Packaging and distribution before adding icons, signing or cross-building.
• Keep Troubleshooting nearby when a build or runtime refuses something.