Flowershow

The fast and simple way to turn markdown into a website

See Flowershow in action on flowershow.app

Monorepo Structure

This is a Turborepo monorepo managed with pnpm workspaces.

apps/
  flowershow/           # Next.js web application (flowershow.app)
  flowershow-mcp/       # MCP server for AI assistants (uses api-contract for typed API calls)
packages/
  api-contract/         # @flowershow/api-contract — Zod schemas, TS types, OpenAPI 3.1 spec
  cloudflare-worker/    # Markdown processing Cloudflare worker
  remark-wiki-link/     # @flowershow/remark-wiki-link — remark plugin for wiki-style links
content/
  flowershow-app/       # Marketing site content (Obsidian vault, not a workspace package)

Quick Start

Prerequisites: Node.js 22+, pnpm, and Docker.

# Clone (include the e2e test-site submodule)
git clone --recurse-submodules https://github.com/flowershow/flowershow.git
cd flowershow

# Install dependencies
pnpm install

# Copy env template (then edit apps/flowershow/.env with your secrets)
cp apps/flowershow/.env.example apps/flowershow/.env

# Start everything: Postgres, MinIO, Inngest, Cloudflare Worker, Next.js app
pnpm dev:up

Visit http://cloud.localhost:3000 once it's running.

If you already cloned without --recurse-submodules, run git submodule update --init to fetch the e2e test site.

Commands

pnpm dev:up --stripe           # Also start Stripe webhook forwarding
pnpm dev:up --github           # Also start Smee (GitHub webhook proxy)
pnpm dev:up --search           # Also start Typesense
pnpm dev:up:all                # Start everything including all optional services

pnpm dev                       # Start dev servers only (no Docker infrastructure)
pnpm dev:down                  # Stop Docker containers (keep data)
pnpm dev:nuke                  # Stop containers + delete all data volumes

pnpm build                     # Build all packages
pnpm test                      # Run tests across all packages
pnpm lint                      # Lint all packages (ESLint for app, Biome for packages)
pnpm format                    # Check formatting (Biome)
pnpm format:write              # Auto-fix formatting

For web app setup (database, storage, auth, etc.), see apps/flowershow/README.md.

Tooling

Tool	Scope	Purpose
Biome	Entire repo	Formatting (single quotes, 2-space indent) and linting for packages/
ESLint	apps/flowershow	Next.js-specific linting via eslint-config-next
Vitest	packages/remark-wiki-link	Unit tests
Playwright	apps/flowershow	E2E tests
Turborepo	Root	Task orchestration and caching
Changesets	packages/	Versioning and npm publishing
Husky	Root	Git hooks (pre-commit runs lint-staged)

A pre-commit hook automatically formats staged files via lint-staged before each commit.

Releasing packages

pnpm changeset                 # Create a changeset describing your change
pnpm version-packages          # Bump versions based on changesets
pnpm release                   # Build all packages and publish to npm

Documentation

• Web app: apps/flowershow/README.md — architecture, local dev setup, environment config, testing, troubleshooting
• REST API contract: packages/api-contract/README.md — Zod schemas, TypeScript types, and OpenAPI 3.1 spec for the Flowershow REST API. The contract is the single source of truth for the API surface; the Next.js API routes, MCP server, and (soon) the CLI and Obsidian plugin all consume it.
• Interactive API docs: With the dev server running, visit http://cloud.flowershow.local:3000/api/docs for Swagger UI, or /api/docs/openapi.json for the raw spec. In production: flowershow.app/api/docs.
• MCP server: apps/flowershow-mcp/ — Model Context Protocol server that exposes Flowershow operations as AI-assistant tools.
• User docs: flowershow.app/docs

Community

• Browse existing issues or submit a new one
• Visit our discussions to ask questions, share ideas, or showcase your Flowershow site

Contributing

We're working on opening up parts of Flowershow for community contributions. While this isn't ready yet, we're excited to welcome contributors soon.

You can already contribute by adding pull requests for demos or tests of Flowershow markdown features:

• Demo: demo.flowershow.app — github.com/flowershow/demo
• Test: test.flowershow.app — github.com/flowershow/test

Development Workflow

1. Create feature branch from staging
2. Implement changes
3. Submit PR to staging
4. After approval, changes are merged to main

We use squash merges to staging with conventional commit messages.