create-swarm-app

Scaffold a new Swarm decentralized storage app in seconds — like create-react-app, but for dapps.

Usage

npm init swarm-app --name <project-name> --type <template>

Example:

npm init swarm-app --name my-app --type node-ts

This creates a my-app/ directory with a working starter project. Then:

cd my-app
npm install
npm start

Templates

| Type | Language | Runtime | Best for | | ---------- | ----------------------- | -------------- | --------------------------------- | | node | JavaScript (CommonJS) | Node.js | Simple scripts, quick experiments | | node-esm | JavaScript (ES Modules) | Node.js | Modern JS with import/export | | node-ts | TypeScript | Node.js | Type-safe backend scripts | | vite-tsx | TypeScript + React | Browser (Vite) | Web UIs for Swarm storage |

What the generated app does

Every template comes with working example code that demonstrates the core Swarm workflow:

Node templates (node, node-esm, node-ts) generate a script that:

1. Connects to your local Bee node
2. Finds an existing usable postage batch, or buys new storage if none exists
3. Uploads a text string to Swarm
4. Downloads it back and prints the result along with the Swarm content hash

Vite template (vite-tsx) generates a React web app that:

1. Gets or creates a postage batch via a button click
2. Uploads a single file to Swarm
3. Uploads a directory of files to Swarm
4. Shows the resulting Swarm hash as a clickable link via the Bee gateway

Options

| Flag | Default | Description | | -------- | ----------------------- | ----------------------------------- | | --name | (required) | Project directory name | | --type | (required) | Template type (see above) | | --host | http://localhost:1633 | URL of your Bee node | | --auth | (none) | API key for authenticated Bee nodes |

Custom Bee host example:

npm init swarm-app --name my-app --type vite-tsx --host http://my-bee-node:1633

Generated project structure

Node template:

my-app/
├── src/
│   ├── index.ts      # Main script — upload/download example
│   └── config.ts     # Bee node URL and client setup
├── package.json
└── tsconfig.json     # (node-ts only)

Vite template:

my-app/
├── src/
│   ├── App.tsx       # React component with upload UI
│   ├── index.tsx     # React entry point
│   └── config.ts     # Bee node URL and client setup
├── index.html
├── package.json
└── tsconfig.json

About bee-js

Generated projects use bee-js, the official JavaScript/TypeScript client for Swarm. The key concepts demonstrated in the templates:

• Postage batches — you pay for storage on Swarm by buying a postage batch. The templates handle finding an existing usable batch or purchasing one automatically.
• Upload — bee.uploadData() / bee.uploadFile() / bee.uploadFiles() store content and return a content-addressed hash.
• Download — bee.downloadData(reference) retrieves content by its hash.

Further reading

• Swarm documentation
• bee-js documentation
• Bee node quick start