Scaffold
Scaffold a New Project
Create a new Dex project with dex scaffold <dir>.
Command
dex scaffold <dir> [options]How It Works
When you run dex scaffold <dir>:
- Prepares Destination Directory: Creates the target folder
<dir>and verifies it is empty. - Project Type Prompt: Interactively asks you to choose a project mode:
spa— Single-Page Application mode (fetchesdex-template-spa.tgz)mpa— Multi-Page Application mode (fetchesdex-template-mpa.tgz)
- Downloads & Extracts Template: Resolves the template archive from GitHub Releases (or custom URL / local file) and extracts project boilerplate files.
- Fetches Framework Packages: Downloads bundled framework package tarballs (
router,server,dev, andpie), extracts them into the localpackages/directory, and sets uppackages/index.ts. - Initializes Metadata: Creates
.dex/metadata.jsonto track the template version and release tag for future updates and syncs. - Verifies Project Structure: Checks that required files (
package.json,dex.config.*,packages/) are present. - Installs Dependencies: Automatically runs
bun installinside the project directory (unless--no-installis specified).
Options
| Option | Description | Default |
|---|---|---|
--repo <owner/repo> | GitHub repository containing template release assets | patrickaigbogun/dex |
--tag <tag|latest> | Release tag to download template from | latest |
--packages-repo <owner/repo> | GitHub repository containing dex-package-*.tgz assets | Template repository |
--packages-tag <tag|latest> | Release tag for dex-package-*.tgz assets | Template tag |
--template <path> | Path to a local .tgz archive (skips GitHub API) | — |
--template-url <url> | Direct URL to download template .tgz (skips GitHub API) | — |
--no-install | Skip running bun install during scaffolding | false |
Examples
Basic Scaffolding
# Scaffold in a new directory
dex scaffold my-blog
# Navigate to the project and start development
cd my-blog
dex startSpecify Release Tag or Custom Repository
# Pin to a specific release tag
dex scaffold my-blog --tag v0.1.44
# Use templates from a custom repository
dex scaffold my-blog --repo myorg/dex-templates --tag v1.0.0Offline / Local Archive Scaffolding
# Use a pre-downloaded template archive and skip dependency installation
dex scaffold my-blog --template ./dex-template-spa.tgz --no-install
cd my-blog
bun installDirect URL Scaffolding
dex scaffold my-blog --template-url https://example.com/templates/dex-template-spa.tgzWhat Gets Created
my-blog/
├─ .dex/
│ └─ metadata.json # Template version and sync tracking
├─ dex.config.ts # Dex framework configuration
├─ package.json # Dependencies and scripts
├─ tsconfig.json # TypeScript configuration
├─ packages/ # Bundled Dex framework modules
│ ├─ router/ # File-based router package
│ ├─ server/ # Server runtime package
│ ├─ dev/ # Dev server and build tool package
│ ├─ pie/ # UI and page helper package
│ └─ index.ts # Package re-exports
├─ web/
│ ├─ pages/ # File-based route components
│ │ ├─ index.tsx
│ │ └─ about.tsx
│ ├─ layouts/ # Layout components
│ │ └─ global.tsx
│ └─ public/ # Static assets (images, fonts, etc.)
└─ routes/ # API and endpoint routesNext Steps
- Start development server:
dex start(orbun run dev) - Edit pages in
web/pages/ - Build for production:
dex build(orbun run build) - Run in production:
dex start -p(orbun run start) - Keep your project updated with upstream template fixes:
dex sync
See Also
- CLI Commands — Full CLI command reference
- Your First App — Step-by-step tutorial
- CLI Flags Reference — Flag summary