Quick start

The quickest way to create a new Bini.js app is using create-bini-app, which sets up everything automatically.

$ npx create-bini-app@latest my-app
$ cd my-app
$ npm run dev

On installation, you'll see the following prompts:

? Project name? (my-bini-app)
 
? Use TypeScript?
> Yes
No
↑↓ navigate • ⏎ select
 
? Styling solution?
> Tailwind CSS
CSS Modules
None
↑↓ navigate • ⏎ select
 
? Which platform would you like to target?
> Web Application
Windows Desktop
Linux Desktop
macOS Desktop
Android
iOS
↑↓ navigate • ⏎ select

CLI flags

Skip prompts by passing flags directly:

System requirements

Before you begin, make sure your development environment meets the following requirements:

• Minimum Node.js version: 20.19.0
• Operating systems: macOS, Windows, and Linux.
• For desktop builds: Windows (C++ Build Tools), macOS (Xcode CLT), Linux (WebKitGTK).
• For mobile builds: Android (JDK 17, Android Studio), iOS (Xcode, CocoaPods).

Supported browsers

Bini.js supports modern browsers with zero configuration.

• Chrome 111+
• Edge 111+
• Firefox 111+
• Safari 16.4+

Native platform support

Bini.js builds for multiple platforms from a single codebase. Use the --platform flag to target a specific platform:

$ npx create-bini-app@latest my-app --platform macos
$ npx create-bini-app@latest my-app --platform android --app-name "My App" --nosign
$ npx create-bini-app@latest my-app --platform windows

Every platform gets the full framework - routing, layouts, API routes, SSG, the overlay, and the rest. The --platform flag only decides what the build targets.

Run the development server

Each platform has its own dev command. Run the one that matches the platform you scaffolded.

Web

$ npm run dev

Starts the Vite dev server and opens your browser automatically.

Windows

$ npm run tauri:dev

Launches the app in a native Windows window with full HMR.

macOS

$ npm run tauri:dev

Launches the app in a native macOS window with full HMR.

Linux

$ npm run tauri:dev

Launches the app in a native Linux window with full HMR.

Android

$ npm run android

Runs the app on a connected Android device or emulator.

iOS

$ npm run ios

Runs the app on a connected iOS device or simulator.

Set up TypeScript

Bini.js now supports TypeScript 7, the native compiler, ~10× faster. Just pick TypeScript in create-bini-app or use the --typescript flag, and the CLI sets everything up for you.

Set up linting

Bini.js uses Oxlint for linting and Oxfmt for formatting - pre-configured and ready to use.

{
  "scripts": {
    "lint": "oxlint",
    "format": "oxfmt",
    "check": "npm run lint && npm run format"
  }
}

These scripts refer to the different stages of developing an application:

• npm run lint - runs Oxlint.
• npm run format - runs Oxfmt.
• npm run check - runs both lint and format.

Set up absolute imports and module path aliases

Bini.js has built-in support for path aliases using the "paths" option in tsconfig.json. These options let you alias project directories to absolute paths, making imports easier to read and refactor:

// Before
import { Button } from '../../../components/button'

// After
import { Button } from '@/components/button'

Path aliases are configured by default:

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"]
    }
  }
}

import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'
import { biniroute } from 'bini-router'
import { biniOverlay } from 'bini-overlay'
import { biniEnv } from 'bini-env'
import { biniSSG } from 'bini-ssg'

export default defineConfig({
  plugins: [
    tailwindcss(),
    react(),
    biniroute(),
    biniOverlay(),
    biniEnv(),
    biniSSG(),
  ],
  resolve: {
    alias: { '@': '/src' },
  },
})