Skip to content
Cloudwerk

Installation

Get started with Cloudwerk by creating a new project or adding it to an existing Cloudflare Workers project.

Prerequisites

Section titled “Prerequisites”

Before you begin, ensure you have:

  • Node.js 20+ - Cloudwerk requires Node.js 20 or later
  • pnpm, npm, or yarn - Any package manager works
  • Cloudflare account - Sign up for free
  • Wrangler CLI - Cloudflare’s CLI tool (installed automatically)

Create a New Project

Section titled “Create a New Project”
Terminal window
npx @cloudwerk/create-app@latest my-app
cd my-app
npm install
npm run dev

The CLI will prompt you to select a UI renderer:

? Select UI renderer:
  ○ Hono JSX (recommended) - Lightweight (~3kb), Workers-optimized
  ○ React - Full ecosystem, larger bundle (~45kb)
  ○ None (API only) - No UI rendering, pure API routes

You can also skip the prompt by specifying the renderer directly:

Terminal window
npx @cloudwerk/create-app@latest my-app --renderer hono-jsx

Manual Installation

Section titled “Manual Installation”

If you prefer to set up Cloudwerk manually or add it to an existing project:

  1. Create a new directory and initialize your project:

    Terminal window
    mkdir my-app && cd my-app
    pnpm init

  2. Install Cloudwerk packages and Hono:

    Terminal window
    pnpm add @cloudwerk/core @cloudwerk/cli @cloudwerk/ui hono

  3. Install development dependencies:

    Terminal window
    pnpm add -D wrangler typescript @types/node

  4. Create a cloudwerk.config.ts file:

    // cloudwerk.config.ts
    import { defineConfig } from '@cloudwerk/core';
    

    export default defineConfig({
      // Your configuration options
    });

  5. Create a tsconfig.json file:

    {
      "compilerOptions": {
        "target": "ES2022",
        "module": "ESNext",
        "moduleResolution": "bundler",
        "strict": true,
        "esModuleInterop": true,
        "skipLibCheck": true,
        "jsx": "react-jsx",
        "jsxImportSource": "hono/jsx",
        "types": ["@cloudflare/workers-types"]
      },
      "include": ["app/**/*", "cloudwerk.config.ts"],
      "exclude": ["node_modules"]
    }

  6. Create your app directory with a home page:

    Terminal window
    mkdir -p app
    // app/page.tsx
    export default function HomePage() {
      return (
        <div>
          <h1>Welcome to Cloudwerk</h1>
          <p>Your full-stack framework for Cloudflare Workers.</p>
        </div>
      );
    }

  7. Add scripts to package.json:

    {
      "scripts": {
        "dev": "cloudwerk dev",
        "build": "cloudwerk build",
        "deploy": "cloudwerk deploy"
      }
    }

Project Structure

Section titled “Project Structure”

After installation, your project will look like this:

my-app/
├── app/
│   ├── page.tsx              # Home page (/)
│   ├── layout.tsx            # Root layout
│   ├── middleware.ts         # Global middleware
│   └── api/
│       └── health/
│           └── route.ts      # API endpoint (/api/health)
├── public/                   # Static assets
├── cloudwerk.config.ts       # Configuration
├── wrangler.toml             # Cloudflare config
├── tsconfig.json
└── package.json

Verify Installation

Section titled “Verify Installation”

Start the development server:

Terminal window
pnpm dev

Open http://localhost:3000 in your browser. You should see your home page.

Next Steps

Section titled “Next Steps”