create-ereo

Scaffold a new EreoJS project with a single command. The create-ereo package provides a project generator with multiple templates and configuration options.

Requirements

• Bun: Version 1.0 or later is required
• Operating Systems: macOS, Linux, Windows (WSL recommended)

Note: create-ereo uses Bun-specific APIs (Bun.write, Bun.spawn) and cannot run directly on Node.js.

Usage

Using bunx (Recommended)

bunx create-ereo@latest my-app

Using npx

npx create-ereo@latest my-app

Direct Installation

bun add -g create-ereo
create-ereo my-app

Command-Line Options

Option	Alias	Description	Default
--template	-t	Template to use	tailwind
--no-typescript		Use JavaScript instead of TypeScript	false
--no-git		Skip git initialization	false
--no-install		Skip dependency installation	false
--help	-h	Show help message

Templates

tailwind (Default)

Full-featured template with Tailwind CSS styling, demonstrating all EreoJS features:

• Tailwind CSS with dark mode support
• Multiple page routes (Home, About, Blog, Contact)
• Dynamic routes with [slug] parameters
• Nested layouts
• Form handling with actions
• Islands architecture with interactive components
• Error boundaries

bunx create-ereo@latest my-app --template tailwind

default

Same as tailwind template - includes all features with Tailwind CSS.

bunx create-ereo@latest my-app --template default

minimal

Bare-bones template for starting from scratch:

• Basic root layout
• Single index page
• No additional styling
• Minimal dependencies

bunx create-ereo@latest my-app --template minimal

tasks

Full-stack CRUD application with authentication and a SQLite database:

• Email/password authentication with JWT sessions
• User registration and login
• Task CRUD (create, read, update, delete)
• Task priorities (low, medium, high) and statuses (todo, in progress, done)
• SQLite database with WAL mode and migrations
• Auth-aware navigation
• Tailwind CSS with dark mode
• Error boundaries and 404 page
• Docker support with SQLite volume mount

bunx create-ereo@latest my-app --template tasks

Template Comparison

Feature	minimal	default / tailwind	tasks
Root Layout	✅	✅	✅
Index Page	✅	✅	✅
TypeScript Config	✅	✅	✅
Dockerfile	✅	✅	✅
Blog (dynamic routes)	❌	✅	❌
Contact Form (action)	❌	✅	❌
About Page	❌	✅	❌
Error Boundary (_error.tsx)	❌	✅	✅
404 Page (_404.tsx)	❌	✅	✅
Navigation Component	❌	✅	✅
Footer Component	❌	✅	✅
Counter Island ('use client')	❌	✅	❌
Tailwind CSS	❌	✅	✅
Dark Mode	❌	✅	✅
Path Aliases (~/)	❌	✅	✅
.env.example	❌	✅	✅
Mock Data Helpers	❌	✅	❌
Type Definitions	❌	✅	✅
Authentication (JWT)	❌	❌	✅
SQLite Database	❌	❌	✅
CRUD Operations	❌	❌	✅

Examples

Basic Project Creation

# Create with all defaults (TypeScript, Tailwind, git, auto-install)
bunx create-ereo@latest my-app

# Navigate and start development
cd my-app
bun run dev

JavaScript Project

bunx create-ereo@latest my-app --no-typescript

Minimal Setup

# Minimal template, skip install (install later manually)
bunx create-ereo@latest my-app --template minimal --no-install

Full-Stack Tasks App

# Tasks template with auth + SQLite
bunx create-ereo@latest my-app --template tasks

Skip Git Initialization

bunx create-ereo@latest my-app --no-git

Project Structure

Tailwind Template

my-app/
├── app/
│   ├── components/
│   │   ├── Counter.tsx       # Interactive island ('use client')
│   │   ├── Footer.tsx        # Footer component
│   │   ├── Navigation.tsx    # Navigation with mobile menu ('use client')
│   │   └── PostCard.tsx      # Blog post card component
│   ├── lib/
│   │   ├── data.ts           # Mock data and helpers
│   │   └── types.ts          # TypeScript type definitions
│   ├── routes/
│   │   ├── _layout.tsx       # Root layout (html, head, body)
│   │   ├── _error.tsx        # Global error boundary
│   │   ├── _404.tsx          # Custom 404 page
│   │   ├── index.tsx         # Home page with loader
│   │   ├── about.tsx         # Static about page
│   │   ├── contact.tsx       # Contact form with action
│   │   └── blog/
│   │       ├── _layout.tsx   # Blog section layout
│   │       ├── index.tsx     # Blog listing page
│   │       └── [slug].tsx    # Dynamic blog post page
│   └── styles.css            # Global Tailwind styles
├── public/                   # Static assets
├── ereo.config.ts            # EreoJS configuration
├── tailwind.config.js        # Tailwind CSS configuration
├── tsconfig.json             # TypeScript configuration
├── Dockerfile                # Multi-stage production Docker image
├── .dockerignore             # Docker ignore patterns
├── package.json              # Dependencies and scripts
├── .env.example              # Environment variables template
├── .gitignore                # Git ignore patterns
└── README.md                 # Project documentation

Minimal Template

my-app/
├── app/
│   └── routes/
│       ├── _layout.tsx       # Root layout
│       └── index.tsx         # Home page
├── public/                   # Static assets
├── ereo.config.ts            # EreoJS configuration
├── tsconfig.json             # TypeScript configuration (if enabled)
├── Dockerfile                # Multi-stage production Docker image
├── .dockerignore             # Docker ignore patterns
├── package.json              # Dependencies and scripts
└── .gitignore                # Git ignore patterns

Tasks Template

my-app/
├── app/
│   ├── components/
│   │   ├── Footer.tsx          # Footer component
│   │   ├── Navigation.tsx      # Auth-aware navigation ('use client')
│   │   └── TaskCard.tsx        # Task card with status/priority badges
│   ├── lib/
│   │   ├── db.ts               # SQLite database, migrations, queries
│   │   └── types.ts            # TypeScript type definitions
│   ├── routes/
│   │   ├── _layout.tsx         # Root layout (html, head, body)
│   │   ├── _error.tsx          # Global error boundary
│   │   ├── _404.tsx            # Custom 404 page
│   │   ├── index.tsx           # Landing page
│   │   ├── (auth)/
│   │   │   ├── login.tsx       # Login form with credentials
│   │   │   ├── register.tsx    # Registration form
│   │   │   └── logout.tsx      # Logout action route
│   │   └── tasks/
│   │       ├── index.tsx       # Task list with filters
│   │       ├── new.tsx         # Create new task form
│   │       └── [id].tsx        # Task detail / edit page
│   └── styles.css              # Global Tailwind styles
├── data/                       # SQLite database directory
│   └── .gitkeep
├── public/                     # Static assets
├── ereo.config.ts              # EreoJS + auth plugin configuration
├── tailwind.config.js          # Tailwind CSS configuration
├── tsconfig.json               # TypeScript configuration
├── Dockerfile                  # Multi-stage Docker image with SQLite volume
├── .dockerignore               # Docker ignore patterns
├── package.json                # Dependencies and scripts
├── .env.example                # Environment variables template
├── .env                        # Local development defaults
├── .gitignore                  # Git ignore patterns
└── README.md                   # Project documentation

Generated Configuration

ereo.config.ts

The configuration file sets up the server, build options, and plugins:

import { defineConfig, env } from '@ereo/core';
import tailwind from '@ereo/plugin-tailwind';

export default defineConfig({
  server: {
    port: 3000,
    development: process.env.NODE_ENV !== 'production',
  },
  build: {
    target: 'bun',
  },
  env: {
    NODE_ENV: env.enum(['development', 'production', 'test'] as const).default('development'),
  },
  plugins: [
    tailwind(),
  ],
});

package.json Scripts

{
  "scripts": {
    "dev": "ereo dev",
    "build": "ereo build",
    "start": "ereo start",
    "test": "bun test",
    "typecheck": "tsc --noEmit"
  }
}

Path Aliases (Tailwind Template)

The tailwind template configures the ~/ path alias for cleaner imports:

// tsconfig.json
{
  "compilerOptions": {
    "paths": {
      "~/*": ["./app/*"]
    }
  }
}

Usage example:

// Before (relative imports)
import { Counter } from '../../../components/Counter'
import { getAllPosts } from '../lib/data'

// After (path aliases)
import { Counter } from '~/components/Counter'
import { getAllPosts } from '~/lib/data'

Dependencies

Runtime Dependencies

Package	Description
@ereo/core	Core framework functionality
@ereo/router	File-based routing
@ereo/server	HTTP server with Bun
@ereo/client	Client-side runtime
@ereo/data	Data loading and actions
@ereo/cli	CLI commands
@ereo/runtime-bun	Bun runtime adapter
@ereo/plugin-tailwind	Tailwind CSS integration
react	React library
react-dom	React DOM renderer

Dev Dependencies

Package	Description
@ereo/testing	Testing utilities
@ereo/dev-inspector	Development inspector
@types/bun	Bun type definitions
@types/react	React type definitions
@types/react-dom	React DOM type definitions
typescript	TypeScript compiler
tailwindcss	Tailwind CSS

Post-Installation Steps

After creating your project:

1. Navigate to Project Directory

cd my-app

2. Install Dependencies (if skipped)

bun install

3. Configure Environment Variables

cp .env.example .env
# Edit .env with your values

4. Start Development Server

bun run dev

Open http://localhost:3000 in your browser.

5. Explore the Code

• Edit app/routes/index.tsx to modify the home page
• Add new routes in app/routes/
• Create components in app/components/
• Configure the app in ereo.config.ts

Troubleshooting

Permission Denied

# On macOS/Linux, ensure Bun is properly installed
curl -fsSL https://bun.sh/install | bash

Directory Already Exists

The generator will not overwrite existing directories. Choose a different name or remove the existing directory:

rm -rf my-app
bunx create-ereo@latest my-app

Network Issues

If dependency installation fails:

bunx create-ereo@latest my-app --no-install
cd my-app
bun install --verbose

Template Not Found

Ensure you're using a valid template name:

bunx create-ereo@latest my-app --template minimal
bunx create-ereo@latest my-app --template default
bunx create-ereo@latest my-app --template tailwind
bunx create-ereo@latest my-app --template tasks

Exit Codes

Code	Meaning
0	Success or --help displayed
1	Missing project name argument

Related

• CLI: dev - Development server
• CLI: build - Production build
• CLI: start - Production server
• CLI: create - Alternative project creation via CLI
• CLI: deploy - Deployment commands