@ampless/admin

日本語版: README.ja.md

ampless

A customization-based CMS for engineers — non-engineers can use the defaults out of the box.

Built on AWS Amplify Gen 2. Engineers customize freely (themes, plugins, schemas — all in TypeScript). Editors get a polished admin UI for posts and media. MCP-native, so Claude / Cursor can be your co-engineer.

Pre-release / beta. Packages publish under the beta npm dist-tag. ampless is on a four-stage release path: alpha (closed dogfood, complete) → beta (public repo; npm beta dist-tag; breaking changes still possible) → RC (feature-complete, breaking changes no longer expected) → stable (v1.0). Today's stage is beta: the source is browsable on GitHub, external users can install, and APIs may still change before RC.

Why ampless

• Customization-based. Themes, plugins, schemas — all in TypeScript. Fork a starter theme, add a plugin as an npm dep, edit React components freely.
• AI-native (MCP). Claude / Cursor / Claude Code can drive your CMS — write posts, customize themes, add plugins through natural language.
• Built on AWS Amplify Gen 2. Cognito for auth, DynamoDB for content, S3 for media, Lambda for plugins. Your own AWS account, your own data.
• Polished admin for editors. Engineers configure, editors operate. Posts / media / settings stay simple for non-engineers.

Quick start

npx create-ampless@beta my-site
cd my-site && npm install
npm run sandbox       # provisions AWS dev resources, then http://localhost:3000

Use the @beta tag while ampless is in beta — @latest is reserved for the eventual v1.0 release.

Sign up at /login — the first registered user is automatically promoted to the ampless-admin Cognito group; subsequent signups land in no group by default and need manual promotion. Full prerequisites, what gets provisioned, and next steps: docs/quickstart.md.

When you're ready to publish, the CLI's --mount mode wires the directory you've been working in to a new GitHub repo + Amplify Hosting app in one shot — see Publishing below.

Stack

Layer	Tech
Frontend	Next.js 16 App Router
UI	shadcn/ui + Tailwind v4
Editor	tiptap (with image/link extensions)
Backend	AWS Amplify Gen 2 (CDK-based)
Auth	Cognito (User Pool + Identity Pool)
Data	DynamoDB
Media	S3 (public/private prefixes, presigned-URL or direct delivery)
API	AppSync GraphQL (custom JS resolvers for public reads)
Plugins	Lambda functions, trust-level segregated, fed by DynamoDB Streams → SQS

Packages

Package	Purpose
ampless	Core types, plugin contract, shared utilities
create-ampless	npx create-ampless@beta — project scaffolding
@ampless/plugin-seo	OGP / Twitter / canonical metadata + sitemap.xml
@ampless/plugin-rss	RSS 2.0 /feed.xml
@ampless/plugin-webhook	POST events to external URLs (HMAC-signed)
@ampless/mcp-server	MCP tool registry shared by the HTTP MCP transport (used by Claude Desktop, Cursor, Claude Code, and other MCP clients)

Plugins in cms.config.ts

import { defineConfig } from 'ampless'
import seoPlugin from '@ampless/plugin-seo'
import rssPlugin from '@ampless/plugin-rss'
import webhookPlugin from '@ampless/plugin-webhook'

export default defineConfig({
  site: { name: 'My Blog', url: 'https://example.com' },
  plugins: [
    seoPlugin({ twitterSite: '@example' }),
    rssPlugin({ language: 'en', limit: 20 }),
    webhookPlugin({
      endpoints: [{ url: 'https://example.com/hooks/ampless', secret: process.env.WEBHOOK_SECRET }],
    }),
  ],
})

Publishing

After you've scaffolded locally and confirmed the sandbox is happy, push the project to GitHub and connect it to Amplify Hosting. Two paths:

CLI (--mount, recommended). From inside the project directory:

npx create-ampless@beta --mount \
  --github-owner <your-user-or-org> \
  --aws-region <region> \
  --create-iam-role           # one-off; reuse `--iam-service-role <arn>` next time

The CLI creates the GitHub repo (gh CLI auth or GITHUB_TOKEN required), creates the Amplify Hosting app, registers the GitHub connection, sets amplify.yml build settings, and kicks off the first deploy. Add --domain / --subdomain to bind a custom domain in the same pass; add --skip-confirm to make it CI-friendly. See npx create-ampless@beta --help for the full flag list.

Manual (console). git init && git push to a repo of your own, then AWS Amplify Hosting console → Create new app → Host web app → connect repo → deploy. Step-by-step in the scaffolded project's README.md ("Deploying to production") and RUNBOOK.md.

Either way the first deploy takes 10–20 minutes (CloudFormation provisions Cognito, DynamoDB, S3, AppSync, Lambda). Subsequent pushes redeploy automatically via the connected branch.

Prerequisites for the CLI flow: AWS CLI (aws configure) and GitHub CLI (gh auth login) authenticated, or supply --github-token directly. Full details land in the scaffolded project's README.md ("Requirements" + "Deploying to production").

Authoring plugins

Want to ship your own plugin? The hands-on walkthrough lives in packages/ampless/docs/plugin-author-guide.md (also available in Japanese as plugin-author-guide.ja.md). The same file ships inside the ampless npm tarball and is copied into every scaffolded project at docs/plugin-author-guide.md, so external authors can read it without checking out this repo.

It covers the Phase 1 + Phase 2 surfaces — descriptor-based head / body injection, admin-managed settings.public values via ctx.setting<T>(), async event hooks, the three trust levels, and publishing to npm. The bundled GA4 / RSS / SEO / Webhook plugins are the working examples it references.

The design rationale stays in docs/architecture/08-plugin-architecture.md; the author guide focuses on what to write and where to put it.

Editor trust model (read this before granting editor access)

ampless treats ampless-editor as a trusted principal — same shape as WordPress's unfiltered_html capability. Editors can store arbitrary HTML / JavaScript in post bodies and the public site renders it verbatim. The full spec is in docs/architecture/04-access-layer-mcp.md; the short version is don't grant editor to anyone you wouldn't also grant admin.

Roadmap

ampless development follows a four-stage release path: alpha → beta → RC → stable. Today's stage is beta: the repo is public, npm packages publish under the beta dist-tag, and breaking changes are still possible before RC. Alpha was the closed dogfood phase. RC is the feature-complete, no-more-breaking-changes phase. v1.0 stable ships simultaneously with the ampless introduction page (built with ampless itself). ampless is positioned as a customization-based CMS for engineers; plugins are npm dependencies that the site engineer audits before installing. A marketplace + runtime sandbox for safely running unaudited third-party plugins is a v2.0+ exploration item, not a committed v2.0 deliverable.

Phase	Highlights
v0.1 (done — internal)	CLI, admin panel, blog template, Cognito, MCP server, SEO/RSS/Webhook plugins
v0.x (in progress)	Theme customization, MCP HTTP transport + access tokens, CloudFront cache strategy, AI provider abstraction, WXR import, monitoring polish
Beta (current public pre-release)	Repo is public, npm beta dist-tag, breaking changes still possible. External plugin authors can publish their plugins to npm (static cms.config.ts consumption); external users can install with full source visibility.
v1.0 RC	Feature-complete; breaking changes no longer expected. First-party sites running on RC builds.
v1.0 stable	Public launch — ampless introduction page (built with ampless) ships simultaneously.
v2.0+	Exploration only — if AmpLess later needs a plugin marketplace: runtime sandbox, dynamic IAM, distribution UI. Not a v1.0 commitment.

Full list in docs/architecture/14-roadmap.md.

Architecture

docs/architecture/ has the design docs split per concern. ARCHITECTURE.md is the table of contents.

Contributing

See CONTRIBUTING.md.

License

MIT