pinme

PinMe

Zero-config deployment tool: upload static files to IPFS, or create and deploy full-stack web projects (React+Vite + Cloudflare Worker + D1 database). Workers also support sending emails via the PinMe platform API.

When to Use

digraph pinme_decision {
    "User Request" [shape=doublecircle];
    "Needs backend API or database?" [shape=diamond];
    "Upload Files (Path 1)" [shape=box];
    "Full-Stack Project (Path 2)" [shape=box];

    "User Request" -> "Needs backend API or database?";
    "Needs backend API or database?" -> "Upload Files (Path 1)" [label="No"];
    "Needs backend API or database?" -> "Full-Stack Project (Path 2)" [label="Yes"];
}

Path 1: Upload Files / Static Sites

Login required. Use pinme login or pinme set-appkey <AppKey> before pinme upload or pinme import.

digraph upload_flow {
    "Install/update pinme to latest" [shape=box];
    "Authenticate" [shape=box];
    "Determine build artifacts" [shape=box];
    "pinme upload <path>" [shape=box];
    "Return preview URL" [shape=doublecircle];

    "Install/update pinme to latest" -> "Authenticate";
    "Authenticate" -> "Determine build artifacts";
    "Determine build artifacts" -> "pinme upload <path>";
    "pinme upload <path>" -> "Return preview URL";
}

1. Check installation and update to latest:

LOCAL=$(pinme --version 2>/dev/null || echo "0.0.0")
LATEST=$(npm view pinme version)
[ "$LOCAL" != "$LATEST" ] && npm install -g pinme@latest || echo "pinme is up to date ($LOCAL)"

2. Authenticate:

pinme login
# or: pinme set-appkey <AppKey>

3. Determine upload target (priority order):

1. dist/ — Vite / Vue / React
2. build/ — Create React App
3. out/ — Next.js static export
4. public/ — Plain static files

4. Upload:

pinme upload <path>
pinme upload ./dist --domain my-site  # Optional: bind subdomain (wallet balance required)

5. Return the final URL printed by PinMe to the user. URL priority is: DNS domain > PinMe subdomain > short URL > preview URL. If it falls back to preview, return the full URL including all hash characters — do not truncate.

Common Examples

pinme upload ./document.pdf          # Single file
pinme upload ./my-folder             # Folder
pinme upload dist                    # Vite/Vue build artifacts
pinme upload build                   # CRA build artifacts
pinme upload out                     # Next.js static export
pinme upload ./dist --domain my-site # Bind PinMe subdomain (wallet balance required)
pinme import ./my-archive.car        # Import CAR file

Do NOT Upload

• node_modules/, .env, .git/, src/
• Only upload build artifacts, never upload source code

---

Path 2: Full-Stack Project

Login required. Uses React+Vite frontend + Cloudflare Worker backend + D1 SQLite database. When designing frontend projects, use Ant Design as the primary design reference, and prioritize following its conventions for layout, components, spacing, and interaction patterns.

digraph fullstack_flow {
    "Install/update pinme to latest" [shape=box];
    "pinme login" [shape=box];
    "pinme create <name>" [shape=box];
    "Modify template code" [shape=box];
    "pinme save" [shape=box];
    "Return preview URL" [shape=doublecircle];

    "Install/update pinme to latest" -> "pinme login";
    "pinme login" -> "pinme create <name>";
    "pinme create <name>" -> "Modify template code";
    "Modify template code" -> "pinme save";
    "pinme save" -> "Return preview URL";
}

Architecture

Layer	Tech Stack	Deploy Target
Frontend	React + Vite (frontend/)	IPFS
Backend	Cloudflare Worker (backend/src/worker.ts)	{name}.pinme.pro
Database	D1 SQLite (db/*.sql)	Cloudflare D1
Object storage	R2 (env.R2)	Cloudflare R2

Capability-Specific Skills

• For Worker file uploads, downloads, images, attachments, media, or object storage, use the pinme-r2 skill. PinMe injects the project bucket as env.R2; do not replace it with D1 BLOBs or Worker filesystem state.

Core Commands

pinme login                  # Login (only needed once)
pinme create <dirName>       # Clone template and create project (auto-fills API URL)
pinme save                   # First deploy / full update (frontend + backend + database, single command)
pinme update-worker          # Update backend only (when only backend/src/worker.ts was modified)
pinme update-web             # Update frontend only (when only frontend/src/ was modified)
pinme update-db              # Run SQL migrations only (when only db/ was modified)

pinme save deploys frontend + backend + database all at once. Only use pinme update-* when you're certain only one part was modified.

Project Structure

{project}/
├── pinme.toml              # Root config (auto-generated, do not modify)
├── package.json            # Monorepo root (workspaces: frontend + backend)
├── backend/
│   ├── wrangler.toml       # Worker config (auto-generated, do not modify)
│   ├── package.json
│   └── src/
│       └── worker.ts       # Backend entry — primarily used for JSON APIs in this template
├── db/
│   └── 001_init.sql        # SQL table definitions
├── frontend/
│   ├── package.json
│   ├── vite.config.ts      # Dev proxy: /api → localhost:8787
│   ├── index.html
│   ├── .env                # Auto-generated: VITE_API_URL (do not modify)
│   └── src/
│       ├── main.tsx
│       ├── App.tsx
│       ├── utils/
│       │   ├── api.ts      # export const API = import.meta.env.VITE_WORKER_URL || ''
│       │   └── config.ts   # Auto-generated: public_client_config (only when auth is enabled)
│       └── pages/
│           └── Home/
│               └── index.tsx
└── .gitignore

First Deployment

LOCAL=$(pinme --version 2>/dev/null || echo "0.0.0")
LATEST=$(npm view pinme version)
[ "$LOCAL" != "$LATEST" ] && npm install -g pinme@latest
pinme login
pinme create my-app
cd my-app

pinme create generates a working Hello World template (includes frontend page + backend API routes + database schema). Modify the template to match the user's business logic — do not write from scratch:

• Modify backend/src/worker.ts — replace API routes
• Modify frontend/src/pages/ — replace page components
• Modify db/001_init.sql — replace table definitions

pinme save
# Single command deploys frontend + backend + database
# Outputs preview URL: https://pinme.eth.limo/#/preview/{CID}

Return the preview URL to the user. Note: return the full URL including all hash characters — do not truncate.

The backend Worker is deployed at https://{name}.pinme.pro. Frontend API requests are automatically configured to point to that address — no manual setup needed.

Subsequent Updates

Changes	Command	Notes
Backend only (backend/src/worker.ts)	pinme update-worker	Faster
Frontend only (frontend/src/)	pinme update-web	Generates new CID
Database only (db/)	pinme update-db	Runs new migrations
Multiple changes or uncertain	pinme save	Safe full deployment

Each frontend deployment generates a new CID and preview URL. Old URLs remain accessible.

---

Worker Code Patterns (backend/src/worker.ts)

In this template, the Worker backend is primarily used for JSON APIs. Prefer standard Web APIs and simple manual routing by default. Worker-compatible libraries can be added when needed, but the default template does not rely on extra frameworks. Avoid packages that depend on a full Node.js runtime, a persistent local filesystem, native binaries, or child processes.

export interface Env {
  DB: D1Database;           // When using database
  R2: R2Bucket;             // Project object storage; injected by PinMe
  API_KEY?: string;         // When using email sending
  JWT_SECRET: string;       // When using JWT auth
  ADMIN_PASSWORD: string;   // When using password auth
}

const CORS_HEADERS = {
  'Access-Control-Allow-Origin': '*',
  'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, OPTIONS',
  'Access-Control-Allow-Headers': 'Content-Type, Authorization, X-API-Key',
};

function json(data: unknown, status = 200): Response {
  return Response.json(data, { status, headers: CORS_HEADERS });
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const { pathname } = new URL(request.url);
    const method = request.method;

    if (method === 'OPTIONS') return new Response(null, { status: 204, headers: CORS_HEADERS });

    try {
      if (pathname === '/api/items' && method === 'GET')  return handleGetItems(env);
      if (pathname === '/api/items' && method === 'POST') return handleCreateItem(request, env);
      return json({ error: 'Not found' }, 404);
    } catch {
      return json({ error: 'Internal server error' }, 500);
    }
  },
};

Worker Constraints and Default Conventions

Item	Notes
Dependency choice	Prefer standard Web APIs and simple manual routing by default. If extra dependencies are needed, prefer Worker-compatible libraries.
Node.js capability	Workers now support part of Node.js compatibility, but they are not a full Node.js runtime. Do not assume all Node.js built-in modules are available or behave exactly the same.
Filesystem	Do not treat a Worker like a server with a persistent local disk. Even if some fs capabilities are available, do not rely on persistence across requests.
Response types	This template mainly uses the Worker for JSON APIs. If there is a clear need, it can also be adapted to return HTML or other content.
Password storage	Never store passwords in plaintext. Use a dedicated password hashing algorithm such as bcrypt, scrypt, or Argon2.
SQL	Do not build SQL by string concatenation. Use parameterized q

---

Content truncated.