Ecopages0.10.0

ecopages CLI

The ecopages npm package is the official and preferred command-line tool for scaffolding and running Ecopages projects.

It is best when you want:

  • Fast project creation from templates
  • Consistent app lifecycle commands (dev, build, preview, start, and types for the type checker)
  • A single entrypoint for common local workflows

Install

You can run the CLI directly with npx, pnpm dlx or bunx (no global install required):

npx ecopages --help

Or install it in a project:

npm install ecopages

Initialize Projects

Init Command

Use the init command with a target directory, then optionally select a template:

npx ecopages init my-app

One-Shot Commands (Complete)

Use these when you want a full bootstrap in one command chain.

JSX template - Creates a minimal Ecopages app with default setup, styled with Tailwind v4 on the Lightning CSS processor. jsx.

npx ecopages init ecopages-app && cd ecopages-app && npm install && npm run dev

JSX with PostCSS template - Creates the JSX app with Tailwind v4 run by the PostCSS processor instead of the default Lightning CSS. Pick it for PostCSS plugins or Tailwind v3. jsx-postcss.

npx ecopages init jsx-postcss-app --template jsx-postcss && cd jsx-postcss-app && npm install && npm run dev

JSX with CSS Modules template - Creates the JSX app styled with plain CSS Modules on the Lightning CSS processor, without Tailwind. jsx-css-modules.

npx ecopages init jsx-css-modules-app --template jsx-css-modules && cd jsx-css-modules-app && npm install && npm run dev

HTML Pages template - Creates an app built from plain HTML Pages, with a src/includes/html.html shell, Tailwind, client navigation, and custom-element islands. html.

npx ecopages init html-app --template html && cd html-app && npm install && npm run dev

Electrobun template - Creates a desktop workspace with an empty Dashboard, an Account Page, and Better Auth sign-in. Ecopages serves Filesystem Routes on loopback and Electrobun opens them in a native window. Requires Bun and pnpm. See the starter README for GitHub OAuth and packaging setup.

pnpm dlx ecopages init desktop-app --template electrobun
cd desktop-app
pnpm install
pnpm desktop:dev

Radiant UI template - Creates an Ecopages JSX app using Radiant UI components and the docs theme preference control. radiant.

npx ecopages init radiant-app --template radiant && cd radiant-app && npm install && npm run dev

Blog with Ecopages JSX - Creates a content-focused blog using the blog-jsx template. blog-jsx.

npx ecopages init blog-jsx --template blog-jsx && cd blog-jsx && npm install && npm run dev

Blog with React - Creates a React-powered blog with routing preconfigured. blog-react.

npx ecopages init blog-react --template blog-react && cd blog-react && npm install && npm run dev

React with PostCSS template - Creates the React app with Tailwind v4 run by the PostCSS processor instead of the default Lightning CSS. Pick it for PostCSS plugins or Tailwind v3. react-postcss.

npx ecopages init react-postcss-app --template react-postcss && cd react-postcss-app && npm install && npm run dev

React with shadcn/ui - Creates the React template configured for shadcn/ui on the React Aria base, with Button, Card, and Input already installed. react-shadcn.

npx ecopages init react-shadcn --template react-shadcn && cd react-shadcn && npm install && npm run dev

React app with Better Auth + Drizzle - Creates a full app template with auth and database workflow included. react-better-auth.

npx ecopages init react-better-auth --template react-better-auth && cd react-better-auth && npm install && npm run db:generate && npm run db:migrate && npm run dev

Step-by-Step (Individual)

1) Basic starter

npx ecopages init ecopages-app
cd ecopages-app
npm install
npm run dev

2) Blog with KitaJS

npx ecopages init blog-jsx --template blog-jsx
cd blog-jsx
npm install
npm run dev

3) Blog with React

npx ecopages init blog-react --template blog-react
cd blog-react
npm install
npm run dev

4) React app with Better Auth + Drizzle

npx ecopages init react-better-auth --template react-better-auth
cd react-better-auth
npm install
npm run db:generate
npm run db:migrate
npm run dev

Runtime Notes

The CLI runs your app on Bun when you launch the command through Bun (bun dev, bun run dev, bunx ecopages …) and on Node with any other launcher. Override it with --runtime bun or --runtime node on the lifecycle commands.

Command Details

This page focuses on setup and project bootstrapping.

For the complete command, flag, and environment variable reference, see CLI Reference.

When To Use ecopages vs @ecopages/* Packages

  • Use ecopages CLI for scaffolding and local app lifecycle commands.
  • Use @ecopages/* packages from npm for framework APIs in app code.

For the complete package map, see Ecosystem Packages.