DEV Community: UnderPeaks

A headless CMS that only gives you an API is only half a product

UnderPeaks — Tue, 13 Oct 2026 12:19:51 +0000

This is how most headless CMS projects go for me. I pick a tool, set up my content models, and get an API. Nice. Then I sit down to build the actual app.

List screen. Detail screen. A form with validation. Loading states, error states, empty states, search, pagination, login. Then I do it all again for the next model, and again on the next project. It’s the same twenty screens every time, and the API didn’t help with any of them.

For years I built apps for small businesses, and almost every one needed the same things: a list of records, a detail page, an add/edit form and a login. Different clients, different logos, same screens. I must have built that set well over a dozen times before it finally annoyed me enough to do something about it.

“Why not just reuse your code?”

I did. Shared widgets, a component library, a starter project I copied from job to job. It helped with the pieces, like buttons, inputs and layouts. But it never saved me the real work, because every client’s data was different. Different fields, different validation, different relationships. So I still ended up editing and customising every screen by hand, every time. A shared library can’t know what your data looks like.

A generator can, because it reads your models.

The API should be where it starts

I’ve been building Underpeaks for about a year and a half now, and one idea keeps coming back to me: the API should be where a backend tool starts. It shouldn’t be where it stops.

If I’ve already told the tool what a Product is, with its fields, types and relationships, then it knows enough to build the screen that lists products, the form that edits them, and the code that talks to the API. Making me write all that by hand is just a choice the tool made.

So Underpeaks generates real Flutter and Next.js apps from your models. One model, two apps, with the data layer already wired up.

The elephant in the room

Let me be straight about what Underpeaks is. It’s a backend. It doesn’t build your product for you.

The generated app is a starting point. You’ll still design your own UI, add your own business logic, and change things to suit your users. I’m not promising a finished app. I’m promising you skip the boring first 80% of wiring screens to an API, so you can get to the part that’s actually yours.

“Generated code is a trap”

I’ve heard that a lot, and I half agree. Most generators have the same three problems. You edit the output, regenerate, and lose your changes. The result looks generic. And you end up stuck with whatever architecture the tool decided on.

Those are fair complaints. I just don’t think the fix is to stop generating code. I think it’s being honest about what generation is for.

For me it’s a head start. The code is normal code and it’s yours, so you can open it, change it, and walk away from the tool tomorrow if you want. The API is still sitting there too. If you don’t like the generated screens, replace them or ignore them and build your own with any HTTP client.

The bit I haven’t cracked yet is keeping generated files and your own files properly separate, so regenerating never wipes out your work. I’m still working on that one, and honestly I’d like to hear how you’d want it to behave.

Why not just ask an AI?

Fair question, and it’s a good option. But AI gives you something a bit different every time, and a generator doesn’t. If I rename a field on a model, I want every screen that uses it to update the same way, not get a best guess. For me, generation covers the repeatable part, and AI is great for everything you build on top of it.

Where I’ve landed

A headless CMS shouldn’t stop at serving data. It should give you the data, the API and a working starting point, and then get out of your way. My test is simple: if you could leave the tool tomorrow and still keep your app, then generating code isn’t a trap. It’s just time saved.

Underpeaks Core is free and self-hosted if you want to have a look: [https://github.com/underpeaks/underpeaks-core]

Over to you

I’d like to know where you stand on this:

Would you rather get just an API, or a working app to start from?
What would make you trust generated code enough to ship it?
What’s burned you before with a code generator?

I’m building this in the open, so what you say really does shape what I do next.

Install Underpeaks Core: A Free, Self-Hosted Headless CMS for Flutter and Next.js

UnderPeaks — Tue, 06 Oct 2026 08:13:39 +0000

If you've ever built the same app for web and mobile, you know the tax: two codebases, two sets of backend glue code, and one data model you keep in sync by hand. Change a field, update it in both places, miss one, ship a bug.

Underpeaks Core is a free, open-source, self-hosted headless CMS built to get rid of that. You define your data model once, and it gives you a backend, a content editor and a REST API. It can also generate working Flutter and Next.js apps from the same model. It's compiled, not AI-generated, so the same model always gives you the same code.

The video above shows the whole install. Here's the written version, so you can follow along or come back to it.

What you need

Node.js and npm
Git
A database: Supabase, PostgreSQL, MySQL, MongoDB or Firebase. Have the connection details ready.
A free Underpeaks account for the license key (step 5)

1. Clone and install

git clone https://github.com/underpeaks/underpeaks-core.git
cd underpeaks-core
npm install

2. Start Core

npm run dev

Open http://localhost:3000. On a fresh install you're taken straight to the installer.

3. Run the installer

You don't write any environment variables by hand. The installer does it for you:

Choose your database
Enter your connection details (it writes your .env for you)
It tests the connection
It creates the system tables
Optionally, it seeds demo content so you have something to explore
You create your admin account

When it's done, you're sent to the sign-in page.

4. Sign in

Use the admin email and password you just created.

5. Add your license key

The first time you sign in, Core asks for a license key:

Create a free Underpeaks account. It takes about 30 seconds.
Copy the license key from your dashboard.
Paste it into Core.

Then you land in the console.

6. Look around

Section	What it does
Shared Models	Define your data models
Pages	Build pages from your models
Menu	Control the admin sidebar
Navigator	Connect pages to each other
Theme	Colours and branding
Storage	Upload and manage media
Users	Manage who can access your instance
Settings	Project name, license key, SMTP, API keys

A good first move is to create a model and attach it to a page. The admin views for it show up straight away.

7. Generate your apps

npm install -g underpeaks-nxf
nxf login
nxf generate flutter   # or: nxf generate nextjs

nxf login opens your browser to connect the CLI to your account. After that, generate gives you a real project you own, with models, an API client and auth flows included.

If something goes wrong

The installer can't connect: check your connection details, and make sure your database accepts connections from where Core is running. Cloud databases often need your IP address allowed.
Something looks off after setup: check that the values in .env.local match your database exactly.

If you get stuck, tell me which step and which database you used. I'm a solo developer and I read every comment.

What's next

The next video in the series is Core vs Studio, the free self-hosted version compared with the hosted one. After that, we create your first model.

Core is free and open source: GitHub.

Which database are you planning to run it on?

How to Self-Host a Headless CMS That Generates Flutter and Next.js Apps (in 5 Minutes)

UnderPeaks — Thu, 01 Oct 2026 11:36:34 +0000

Underpeaks Core is an open-source, self-hosted headless CMS built to remove that tax. You define your data model once, and it gives you a backend, a content editor, a REST API — and, if you want it, a working Flutter app and Next.js app compiled from that same model. No AI involved: same model in, same code out, every time.

In this guide you'll go from zero to a running Core instance on your own machine.

What you'll need

Node.js and npm
Git
A database: Supabase, PostgreSQL, MySQL, MongoDB or Firebase — whichever you're most comfortable with. Have its connection details ready (host and credentials, or project URL and keys).

Step 1: Get a free license key

Core is free and open source (Apache 2.0), but it needs a license key — that's what lets the CLI generate code for your projects.

Sign up for a free account at underpeaks.com
Generate a license key from your dashboard
Keep the tab open — you'll paste the key during setup

Step 2: Clone and install

git clone https://github.com/underpeaks/underpeaks-core.git
cd underpeaks-core
npm install

Step 3: Start Core

npm run dev

Open http://localhost:3000. On a fresh install, you're sent straight to the installer.

Step 4: Run the installer

There are no environment variables to write by hand — the installer does it for you:

Choose your database — one of the five supported options
Enter your connection details — the installer writes your .env configuration
Connection test — confirms Core can reach your database
Table creation — creates the system tables Core needs
Demo content (optional) — seeds an example project so you have something to explore straight away
Admin account — the email and password for your first user
License key — paste the key from step 1

When it finishes, you're redirected to sign in.

Step 5: Take the tour

Section	What it does
Shared Models	Define your data models — the schemas everything else is built on
Pages	Build admin and client-facing pages from your models
Menu	Control your sidebar navigation
Navigator	Map how pages connect to each other
Theme	Colours and branding
Storage	Upload and manage media
Users	Manage who can access your instance
Settings	Project name, license key, SMTP, API keys

A good first exercise: create a model under Shared Models (say, Product with a title, price and image), then attach it to a page under Pages. The admin views for it appear instantly — no extra configuration.

Step 6: Generate your apps

Once a model is attached to a page, install the CLI and generate:

npm install -g underpeaks-nxf
nxf login
nxf generate flutter   # or: nxf generate nextjs

nxf login opens your browser to connect the CLI to your account; after that, generate produces a real project you own — models, API client and auth flows included.

Troubleshooting

Installer can't connect: double-check your connection details, and make sure the database is reachable from where you're running Core (cloud databases often need your IP allowed).
Something looks off after setup: check that your .env.local values match your database exactly.

What's next

Full code generation guide: docs
Source code: GitHub

If you try it and something breaks or confuses you, I'd genuinely like to know — open an issue on GitHub or drop a comment below. Underpeaks is built by one developer, and feedback from real setups is the most useful thing I can get.

Why we built a five-database adapter layer (and what it cost in build time)

UnderPeaks — Tue, 29 Sep 2026 12:21:25 +0000

Every developer has had this moment. You pick a database on day one (Firebase because it's fast, Mongo because it's flexible, Postgres because it's "the right choice") and six months later you'd pick differently. By then, the database has leaked into everything.

When I started building Underpeaks, a headless CMS that generates Flutter and Next.js apps from one data model, I made a decision that cost me far more time than I expected: it would run on five databases (Supabase, PostgreSQL, MySQL, MongoDB and Firebase) behind one interface.

Here's why, how it works, and what it actually cost.

Open source isn't the same as portable

"Open source" is table stakes for a CMS now. But open source doesn't mean you can leave. Most tools bake in one database, and switching means a rewrite: queries, auth, migrations, the lot.

I wanted the opposite. Your data model should be the source of truth, and the database should be a decision you can change your mind about.

One interface, five engines

Everything in Underpeaks Core talks to a single DBAdapter interface. Routes never import a database driver directly. They ask for the configured adapter:

const adapter  = getConfiguredAdapter()
const dbConfig = adapter.config

const users = await adapter.readAll(dbConfig, 'nxf_users')

Each adapter implements the same methods (create, read, readAll, update, delete, plus auth helpers) for its own engine. Swap the adapter, and the rest of the codebase doesn't know or care.

That's the easy part to describe. The hard part is that five databases disagree about almost everything.

Where the databases disagree

Primary keys. SQL tables often use id. But a model called products might declare product_id as its primary key, and Firebase documents have IDs that aren't fields at all. Every update and delete has to know which column is the real key, so the interface takes it explicitly:

await adapter.update(dbConfig, 'products', productId, data, 'product_id')

Forget that last argument on a model whose key isn't literally id, and the update silently matches nothing. I learned that one the hard way.

Concurrency. Firing off parallel queries with Promise.all is harmless with Firebase or Supabase's HTTP client. With a pooled Postgres or MySQL connection, it can exhaust connections or interleave in ways you don't expect. The SQL adapters now read sequentially. It's slower on paper and far more predictable in practice.

Response shapes. One path returned { data }, another returned { records }. Generated apps expecting one shape silently got undefined from the other. Consistent envelopes aren't glamorous, but they're the difference between "it works" and "it works on my database."

Schema. SQL wants real tables and columns. MongoDB and Firebase are happy with whatever you send. The adapter layer has to create physical tables where the engine needs them, and enforce structure where the engine won't.

What it cost

Honestly? Much more than I planned. Supporting one database would have taken about [2-3 weeks]. Five took [4-5 months].

The cost isn't writing five adapters. It's that every feature now has five edge cases. Auth, file storage, pagination and filtering each work slightly differently per engine, and every bug has to be checked against all five. A fix that's correct for Postgres can be wrong for Firebase.

The trade-offs, honestly

A single-database tool can do things this approach can't:

Use engine-specific features freely. Postgres full-text search, Mongo aggregation pipelines, Firebase realtime listeners. An adapter layer has to target what all five share, or handle each specially.
Move faster. One engine means one set of edge cases.
Tune performance deeply for that one database.

If you know you'll only ever use Postgres, a Postgres-native tool is a perfectly good choice.

Who it's for

The adapter layer is for developers who:

already run a database and don't want to migrate to use a CMS
build for clients with different infrastructure
want the option to change their mind later without a rewrite
Database freedom as insurance

I don't think of multi-database support as a feature you use every day. It's insurance. Most projects will never switch databases, but knowing you can changes how comfortably you commit.

Underpeaks Core is open source and self-hosted. Pick your engine, and keep the option to change your mind.

👉 Try Underpeaks Core

Github: Underpeaks_core

Why I Made the Data Model the Single Source of Truth for Both Mobile and Web

UnderPeaks — Thu, 24 Sep 2026 08:25:14 +0000

When you're building a product that needs both a mobile app and a web app, there's a decision point early on: do you build two frontends against one backend, or do you try to share more than that?

Most teams end up with two frontends, one backend, and a growing list of small inconsistencies between them. A field gets added on mobile and forgotten on web. A validation rule changes in one place and not the other. Nothing catastrophic, just a slow accumulation of drift.

I built Underpeaks around a different assumption: the schema shouldn't just define your backend, it should define your applications too.

How that plays out technically

A model in Underpeaks isn't just a database table definition. It carries enough information, field types, UI hints, relationships, validation, to generate a working page in both a Flutter app and a Next.js app. Change the model, regenerate, both applications reflect the change.

The generation isn't destructive either. Files you've customized are tracked via checksums and left untouched on regeneration. Only genuinely new pieces (a newly added field, say) get merged in. This matters a lot in practice, generated code you can't safely touch is generated code you'll eventually abandon.

The database layer

Underpeaks runs on five database backends (Supabase, Postgres, MySQL, MongoDB, Firebase) through one adapter interface. This was a deliberate choice: teams shouldn't have to commit to a database vendor just to use a code generation tool. Same schema, same generated output, regardless of which one sits underneath.

Self-hosted by default philosophy

Underpeaks Core is free, open source, and self-hosted. I built it this way first, before the hosted version, because I wanted the tool to work fully even for someone who never pays for anything. Underpeaks Studio (hosted) exists for teams that want managed infrastructure, not because the self-hosted option is deliberately limited.

Launching on Product Hunt today: https://www.producthunt.com/products/underpeaks?launch=underpeaks

Genuinely interested in hearing how other people have approached this same problem, shared schemas, code generation, monorepo strategies, whatever's worked or not worked for you.

I got tired of building the same backend twice, so I built a tool that generates it for me

UnderPeaks — Thu, 24 Sep 2026 08:03:07 +0000

Every time I shipped a product that needed both a mobile app and a web app, I ended up doing the same thing: build the backend, build the Flutter app on top of it, then build a whole separate Next.js app on top of the same data, and keep both in sync by hand every time the schema changed.

That got old fast. So I built Underpeaks.

How it actually works

You define your data model once in the console, fields, types, relationships. From that one schema, Underpeaks generates:

A real Flutter app, with your choice of Riverpod, Provider, or BLoC
A real Next.js app, with your choice of Zustand, React Query, or Jotai
A REST API
An admin dashboard with KPIs and charts, if you want it

Not scaffolding. Real, readable source code, using the state management pattern you already know.

The database question

Underpeaks isn't tied to one database. Five adapters ship out of the box: Supabase, Postgres, MySQL, MongoDB, Firebase. Same interface regardless of which one you pick, so if you start on Supabase and later need to move, your schema and generated code come with you.

Self-hosted, actually

Underpeaks Core is free, open source, and runs on your own infrastructure. No calling home, no feature gates you didn't agree to. Underpeaks Studio is the hosted version if you'd rather not run it yourself.

Launching on Product Hunt today, would love feedback from people who've hit the same problem: https://www.producthunt.com/products/underpeaks?launch=underpeaks

Happy to answer anything in the comments, architecture, tradeoffs, what's still rough around the edges. It's a solo build, so there's plenty.