slim-minima
geraldho81/slim-minima
A minimal, self-hosted CMS for marketers. Block-based pages, blog & media on your own Neon Postgres + Cloudinary. Next.js, SEO & GEO ready, with an AI/MCP connector & REST API for Claude, ChatGPT & coding agents.
Instalação
npx convez-ai geraldho81/slim-minima1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
Slim Minima - a minimal, self-hosted CMS for marketers
A CMS built for marketers, by marketers.
Block-based pages, blog, and media on Next.js + Neon Postgres + Cloudinary. SEO and GEO ready, with an AI/MCP connector and REST API for Claude, ChatGPT, and coding agents.
The content layer without the bloat. Slim Minima gives you pages, posts, and a media library that are SEO and GEO ready out of the box, then gets out of your way so you can build the rest of your site with a coding agent like Claude Code or Codex. Everything lives in your own Neon Postgres database and your own Cloudinary account. Nothing is hosted by us.
Built on Next.js (App Router), Drizzle ORM, Auth.js, and Tailwind.
What you get
- Visual page builder - a palette of blocks, drag to reorder, autosave, revisions, scheduling, draft preview.
- Block engine - typed blocks you can extend with one file. The editor form, validation, REST API, and renderer all pick new blocks up automatically.
- Blog - article-first editor, categories, tags, hero images, RSS.
- Media library - Cloudinary-backed uploads with alt text and a 30-day trash bin that syncs deletions to Cloudinary.
- Contact forms - a configurable block: define your own fields, set the receiver email, reply inline or redirect to a thank-you page.
- Menus, settings, users - header/footer nav, site identity, admin/editor roles.
- SEO and GEO - canonical URLs, JSON-LD, sitemap, robots, RSS, plus LLM-native
/llms.txt,/llms-full.txt, and a markdown view of every page (/<slug>.md). - Agent access - a content CLI (
npm run cms) and an API-key REST API (/api/v1) so agents can build and edit content. - AI connector (MCP) - a built-in Model Context Protocol server. Connect Claude, ChatGPT, Perplexity, or Grok to read your pages and posts and write blog posts in plain language. Auto-provisioned: copy the URL and token from Settings.
What you'll need (free tiers are fine)
| Service | Why | Required |
|---|---|---|
| Neon | Postgres database | Yes |
| Cloudinary | Media storage and delivery | Yes (for media) |
| Resend | Email contact-form submissions to you | Optional |
Each is your own account. See .env.example for every variable and where to find it.
Only DATABASE_URL and AUTH_SECRET must be set as environment variables.
Everything else - Cloudinary, Resend email, the upload folder, the trash
retention - can be added later directly in the CMS (Admin -> Settings),
with no redeploy. So you can ship the site live first and connect the rest from
the dashboard. Environment variables always take precedence when both are set.
(The only env-only optionals are CRON_SECRET and NEXT_PUBLIC_SITE_URL.)
Quick start
npm install
cp .env.example .env.local # fill in DATABASE_URL (Neon) + AUTH_SECRET + Cloudinary
npm run db:migrate # create tables in Neon
npm run seed # first admin + sample home/about/blog
npm run dev
npm run seed creates the first admin and prints its email and a generated
password once - copy them. (To choose your own, set SEED_ADMIN_EMAIL,
SEED_ADMIN_PASSWORD, and SEED_ADMIN_NAME in .env.local before seeding, or
run npm run cms -- create-admin --email you@example.com --password yourpass.)
Open http://localhost:3000 (site) and http://localhost:3000/admin (sign in).
Cloudinary note: Cloudinary blocks delivery of PDF and ZIP files by default. To allow them, open your Cloudinary console and go to Settings -> Security -> "PDF and ZIP files delivery" and tick "Allow delivery of PDF and ZIP files".
Build your site on top of Slim Minima (for AI coding agents)
This repo is the foundation. Open it in Claude Code, Codex, or Cursor and tell the agent to build your site. Paste the prompt below to start.
Prompt to give your agent: "Read
AGENTS.mdbefore writing any code. You are building a marketing site on top of Slim Minima. Do not change the CMS internals unless I ask. Build my pages by adding/editing blocks, add new block types when needed, and retheme by editing the CSS variables. Runnpm run typecheckandnpm run buildbefore telling me you're done."
What an agent should know (the short version):
- Read
AGENTS.mdbefore writing any code. It is the contract: content model, the block engine, CLI/REST reference, the SEO/GEO checklist, the contact form, the media trash bin, and the retheming guide. - Set up the environment first - the app will not run without it. Run
cp .env.example .env.local, then ask the site owner for their own API credentials and fill them into.env.local:DATABASE_URL(Neon),AUTH_SECRET(openssl rand -base64 32), and the threeCLOUDINARY_*keys are required; Resend is optional. Never edit.env.exampleor commit real keys. Then runnpm run db:migrate && npm run seed && npm run dev. If a required key is missing, stop and ask the owner - do not use placeholders. - To build pages, either use the visual admin, or create them as code with
the CLI:
npm run cms -- create-page --title "Pricing" --blocks-file blocks.json --publish. A page is an array of blocks; runnpm run cms -- get-page homeafter seeding to see a real example. - To add a new section type, create one file in
src/blocks/<name>/index.tsxand register it insrc/blocks/registry.ts. The palette, settings form, validation, REST API, and renderer pick it up automatically. See the walkthrough inAGENTS.md. - To restyle, edit the CSS variables at the top of
src/app/globals.cssfirst (--bg,--text,--accent,--radius, ...), then thecms-*classes. The font is insrc/app/layout.tsx. Admin uses separate--ad-*variables - do not touch those. - Always verify:
npm run typecheck && npm run build. There is no test suite; a green build plus a manual check is the bar.
Rules an agent must follow:
- Keep the SEO/GEO features working (sitemap, JSON-LD,
llms.txt, the per-page.mdview). When you add a block with text, add an emitter insrc/lib/block-text.tsso it appears in the markdown/LLM output. - Keep it minimal - that is the brand.
- In all generated copy and UI: no em dashes or en dashes, and no AI vocabulary (delve, vibrant, tapestry, crucial, showcase, foster, ...).
- Never put a
borderoroutlineon card-style elements; cards are defined by their background alone. - Do not add
three,gsap, orlenisto the default build. Animation is the opt-inextras/immersive/module only.
Want an immersive, animated site?
The default front end ships with zero animation libraries to keep it fast. An
opt-in module in extras/immersive/ adds a WebGL hero (three.js) and a GSAP +
Lenis animation layer, loaded lazily so they never bloat the initial bundle.
They are excluded from the build until you wire them in. See
extras/immersive/README.md.
Deploying
Push to a Git repo and deploy to any platform that supports Next.js (Vercel,
Netlify, Railway, Fly.io, a VPS, etc.). Set the environment variables from
.env.example. The media trash bin's 30-day purge runs from a daily cron -
vercel.json declares it for Vercel (/api/cron/empty-trash); on other
platforms set up an equivalent cron that hits that endpoint. Set CRON_SECRET
so only your platform can trigger it.