Build and Launch a Keyword-Focused AI Site Fleet with shipwords

What shipwords does

shipwords is an open-source, MIT-licensed framework for running a fleet of AI image and video sites on Cloudflare, with one site dedicated to each keyword. Shared capabilities such as accounts, payments, credits, and AI generation are implemented once in the framework, while every site can have its own pages, visual identity, domain, database, storage, and payment account.

Each site is a TanStack Start and React 19 application running on its own Cloudflare Worker, with D1, R2, and Workflows. This separation lets you launch, update, or retire sites independently while still receiving improvements to the shared core on future deployments.

Key features

• Google and email sign-in with account pages.
• Stripe and PayPal support, including credit packs, subscriptions, orders, refunds, and disputes.
• Email notifications and free guest tries with reCAPTCHA v3 abuse limits.
• Privacy, terms, refund, and DMCA pages.
• SEO and GEO helpers, including sitemap.xml, robots.txt, and llms.txt.
• A workflow-based generation runtime with one-way job states and automatic refunds for failed jobs.
• Yir API integration for models such as GPT Image, Nano Banana, Seedream, FLUX, Seedance, Veo, Kling, and Wan.
• A mock upstream for local development without a model API key.
• Optional video composition with an ffmpeg container.

Prerequisites

Before starting, install Node 24, as specified by the repository's .nvmrc, and pnpm 10. Enable Corepack so the expected pnpm version is available:

corepack enable

On Windows, use Git Bash or WSL. A Cloudflare account and a Stripe or PayPal account are required when you are ready to deploy and accept payments. They are not required for the basic local setup.

Install the repository

Fork or clone the repository, then install its dependencies:

pnpm install

Scaffold a new site

Use the site generator to create a site from the complete AI site template. The first argument becomes the directory under sites/, and the domain is recorded for the site configuration:

pnpm new-site my-tool --domain my-tool.com
pnpm install

The generated site includes a home page, pricing, account and login flows, policy pages, and the standard sitemap.xml, robots.txt, and llms.txt files. Run pnpm install again so dependencies for the new site are installed.

Configure local secrets

Keep local secrets outside the repository. Create a configuration directory, copy the generated site's example variables file, and connect the worktree configuration:

mkdir -p ~/.config/shipwords
cp sites/my-tool/.dev.vars.example ~/.config/shipwords/my-tool.dev.vars
pnpm setup:worktree

The example configuration is designed to work immediately for local development. Email sign-in codes are printed in the development server's terminal, new accounts receive sign-up credits, and generation uses the mock upstream when UPSTREAM_MOCK=1. This means you can test the application without a model API key.

Add real generation

For real model requests, add a Yir API key and turn off the mock upstream by changing UPSTREAM_MOCK.

Test payments

To test credit purchases, add a Stripe test key beginning with sk_test_. From the site directory, run the repository's webhook forwarding utility so local development can receive Stripe events:

node ../../tools/stripe-listen.mjs

The shared payment code is designed to handle repeated or out-of-order payment events, double charges, and refunds for failed jobs.

Configure optional sign-in and guest access

Guest free tries require reCAPTCHA keys. Without them, visitors must sign in before their first generation. Google sign-in is optional; if enabled, create a Google OAuth client and use http://localhost:<port> as an allowed origin. Email sign-in works without Google OAuth.

Run the site locally

Change into the generated site, create the local database artifacts, apply local migrations, and start the development server:

cd sites/my-tool
pnpm db:generate && pnpm db:migrate:local
pnpm dev

Open the local URL printed by the development server. You can exercise email authentication, account creation, credits, and mock generation using the example configuration.

Use the repository commands

Most commands can be scoped to a site or used for repository-wide checks:

pnpm new-site <dir> --domain <domain>
pnpm list-sites
pnpm setup:worktree
pnpm --filter "./sites/<site>" dev
pnpm --filter "./sites/<site>" check
pnpm check:packages
pnpm check:template
pnpm lint && pnpm test:tools

The list-sites command builds a site list from each site's code and README. A site's check command runs type checking, a build, and launch checks. Package checks cover the shared core and jobs packages, while template and tools checks help catch problems before launch.

Build a site with an AI coding agent

If you already know the keyword you want to target, the repository supports an agent-driven workflow. In Claude Code, Codex, or Cursor, provide the repository's agent instructions and ask it to build the site:

Read shipwords.dev/llms.txt and build a site for "<your keyword>"

The agent can clone the repository, create the site, and run it locally. The rules for AI coding agents are documented in AGENTS.md. If you need ideas for emerging keywords, the separate new-term-radar project monitors new AI terms on X, Hugging Face, GitHub, and sitemaps.

Customize advanced site behavior

Use the shared generation runtime

The packages/jobs package provides a workflow-based runtime, an upstream adapter interface, the Yir adapter, a local mock upstream, and optional ffmpeg composition. Keep site-specific generation behavior in the site's configuration and use the shared runtime for job processing and refund handling.

Set generation cost limits

Model calls through Yir are billed per request. Each job's maximum cost is set in site.models.ts. Review these limits before enabling real generation so the site's pricing and credit behavior match the maximum upstream cost.

Study the video example

For a video-focused site, inspect sites/tinydeskai-example. It is the full source for Tiny Desk AI and demonstrates photo slots, one-pass video editing, output checking, ffmpeg composition, and content pages. Its workflow turns a viral clip into a template that visitors can use with uploaded photos.

Keep sites independent

Every site is deployed independently with its own database, storage, and payment account. This architecture allows you to improve the shared core once and deploy the update to selected sites without coupling their launches or retirements.

Prepare for production

When the local site is working, follow the site launch handbook for the production process. Plan for domain costs, Cloudflare usage, payment processing fees, and Yir model requests. Video sites that stitch clips together use Cloudflare Containers and require the Workers Paid plan.

Before launch, verify the site's authentication, payment webhooks, credit behavior, generation failures, refunds, policy pages, SEO files, and analytics configuration. The repository also provides architecture and local-development documentation for deeper configuration details.

Conclusion

shipwords provides a practical foundation for launching multiple keyword-focused AI sites without rebuilding authentication, billing, credits, generation workflows, and SEO support for every project. Start with the template, use the mock upstream for local testing, add real providers when ready, and deploy each finished site independently on Cloudflare.