NextBlock ships improvements continuously — new blocks, editor fixes, security patches, and occasionally a database change that the new code depends on. Keeping up with all of that used to mean knowing which install path you were on. It no longer does. Every NextBlock project, however it was created, understands one command:
npm run update
Code · dependencies · database schema — in that order, in one step.
It figures out which kind of install it is running inside, picks the right source for new code, installs the matching dependencies, and then applies any database migrations the new version needs. If you would rather look before you leap, npm run update:check lists what would change and touches nothing.
Five ways to install, four ways to update
The first four options in the install guide map one-to-one onto the paths below. The fifth, where an AI coding agent builds the site, updates like path 2 or 3. The command is the same everywhere; what differs is where the new code comes from.
Automatic after setup
One-click Vercel & GitHub forks
One-time setup: Connect GitHub in the dashboard, or enable Actions on a manual fork. Then a daily workflow merges upstream and Vercel redeploys.
2One command
npm create nextblock → Docker
Update, then rebuild the local stack. Your Postgres and media volumes survive untouched.
3One command
npm create nextblock → Supabase
New framework files come from npm; your own pages, routes and content are left alone.
4One command
git clone the monorepo
A guarded git pull or upstream merge, then dependencies and migrations. No manual steps.
Installed by an AI coding agent?
Then you have an ordinary npm create nextblock project. The agent runs npx create-nextblock@latest my-site --non-interactive, which scaffolds the same standalone app. It runs in Docker by default, so it updates like path 2. With --mode cloud it uses managed Supabase and updates like path 3. If the agent runs the update for you, have it use node tools/update.mjs --yes. Its shell is not an interactive terminal, so without that flag the updater declines. More on this route in the install guide.
1. One-click Vercel and GitHub forks — hands-off
This path updates itself. When you deployed, Vercel created a repository you own; the dashboard’s Connect GitHub onboarding step installs a workflow into it that runs every day at midnight UTC and can also be triggered by hand from your repository’s Actions tab. A manual GitHub fork already carries the workflow, but GitHub disables Actions on forks. Enable them once from the fork’s Actions tab.
What qualifies — it is the repository, not the host
The workflow merges the NextBlock monorepo into your repository, so it only works where your repository is that monorepo: a one-click deploy, a GitHub fork, or a clone. A project created with npm create nextblock is the flattened standalone app — app/, components/ and lib/ at the root — and merging apps/, libs/ and nx.json into it would wreck it. Pushing that project to GitHub and deploying it on Vercel does not change its shape: it is still an npm run update install, and NextBlock will not offer it this workflow. Docker is a separate question entirely — that is how you run a project, not what shape its repository is.
- The workflow merges the latest upstream NextBlock into your deploy branch.
- A clean merge is pushed to your branch, which triggers an ordinary Vercel deployment.
- During that production build, NextBlock applies any pending database migrations before the app is built — so new code never runs against an old schema.
- If the merge conflicts, nothing is pushed. The workflow opens a GitHub issue instead, and your CMS dashboard shows an amber banner linking straight to it. Resolve it, close the issue, and the banner clears itself.
Make the repository public
A public repository is completely zero-config. On a private one, add a NEXTBLOCK_GITHUB_TOKEN environment variable with read access to issues so the conflict banner still works — and note that Vercel’s free Hobby plan refuses to auto-deploy automated commits on private repositories, so the merge would land without deploying.
Working on a local clone of that fork? npm run update does the same merge on your machine, adding an upstream remote if it is missing, then installs dependencies and applies migrations.
2. npm create nextblock → Docker — update, then rebuild
From your project directory:
npm run update
npm run docker:upThe first command updates the application and its dependencies and stages the new migrations; the second rebuilds the containers and applies those migrations. The self-hosted stack runs its own migration service, so the updater hands the schema step to it rather than applying the same SQL through two different trackers. Your database and media live in Docker volumes and are never touched by either command — docker:up rebuilds images, not data.
3. npm create nextblock → managed Supabase — one command
npm run update
npm run build
npm startYour project is a standalone Next.js app with no upstream to pull from, so new framework code comes from the published create-nextblock package on npm — the exact artifact your project was scaffolded from, versioned in lockstep with the release. NextBlock fetches both your current version and the new one, and applies the difference between them as a git 3-way merge, so the update behaves exactly like a git pull: files you never touched update silently, files you customised keep your changes. It then merges the new dependency versions into your package.json, runs npm install, and applies migrations.
This needs a git repository with at least one commit and a clean working tree — commit your work before updating. Without that there is nothing to merge against, so the files are copied instead and anything replaced is kept under .nextblock-backup/.
A new project needs that first commit. The create-nextblock CLI runs git init but commits nothing, in Docker mode too and when an AI agent runs it. So commit once before your first update: git add -A, then git commit -m initial. The generated .gitignore already keeps your .env files and the agent’s MCP configs out of git.
Deploying to Vercel from this project
Run npm run update locally, commit the result, and push. Your production build applies any pending migrations on the way up, exactly as it does for one-click installs.
4. The cloned monorepo — one command
npm run update
npm run devIn a clone of the NextBlock repository this fast-forwards your checkout, reinstalls workspace dependencies and applies pending migrations. It refuses to run over uncommitted changes and tells you how to stash them first, so an update can never silently eat work in progress. If you have local commits, it stops and points you at git pull --rebase rather than guessing. When it finishes, restart the dev server with npm run dev (port 4200).
What npm run update actually does
- Identifies the install. Monorepo or standalone app; git-backed or npm-backed; Docker or not.
- Updates the code from the right source — an upstream git merge, a fast-forward pull, or the published
create-nextblockpackage. - Installs dependencies with
npm install, so the code and the packages it imports move together. - Refreshes the migration files shipped inside
@nextblock-cms/db, so the newest schema changes are on disk before anything is applied. - Applies pending migrations, listing them first and asking before it writes.
- Clears the dashboard’s update banner once the new version is really in place.
Options
| Command | What it does |
|---|---|
npm run update | Code, dependencies and schema. |
npm run update:check | Report what would change. Writes nothing. |
npm run update -- --yes | Skip the confirmation prompts. Useful in CI. |
npm run update -- --db-only | Apply pending migrations and nothing else. |
npm run update -- --skip-db | Update code and dependencies, leave the database alone. |
npm run update -- --force | Run even when you are already on the latest version. |
On PowerShell, a bare -- is stripped, so the flagged forms above run as a plain npm run update, with its confirmation prompts. npm keeps the flag for itself: it warns Unknown cli config for --check, --db-only and --skip-db, but --yes and --force are npm options too, so it takes them without that warning. To preview, use npm run update:check. For the other options, call the script directly. For example, in a project made with npm create nextblock, run node tools/update.mjs --db-only; in the monorepo, node apps/nextblock/tools/update.mjs --db-only. Command Prompt (cmd.exe) and macOS or Linux shells are not affected.
What happens to your database
Schema changes are forward-only. NextBlock never rewrites or replays a migration that has already run: each one is applied and recorded in the same transaction, so a failure rolls back cleanly and leaves the database exactly as it was. Already-applied migrations are skipped by version, which makes re-running an update completely safe.
Migrations mostly change structure — tables, columns, indexes, permissions. A few also fix data. They refresh the demo content, theme colours and interface strings NextBlock seeded, usually only where these still match what NextBlock shipped. Rarely, one applies a narrow mechanical fix across all content. Examples: moving YouTube embeds to youtube-nocookie, or removing a CSS class that slowed the first paint. No migration deletes your pages, posts, products, media or users.
Belt and braces
Before a big jump on a production site, take a database snapshot. Supabase keeps daily backups on paid plans, which you restore from Database → Backups in its dashboard. For a copy of your own, use pg_dump with your database connection string. With the Supabase CLI, supabase db dump saves only the schema; run supabase db dump --data-only as well for the rows. On Docker, run pg_dump inside the db container. Then run npm run update:check to preview the update before you commit to it.
If something goes wrong
- Standalone projects: the update is applied as a git 3-way merge into your working tree — nothing is committed for you. Review it with
git status, which lists the files it added, andgit diff. To back the code out, rungit reset --hard HEADandgit clean -fd, thennpm installto restore your dependencies.git cleanremoves the files the update added, plus any untracked file you created since; preview it withgit clean -nd. Migrations that already ran stay applied: restore your snapshot if you need the old schema. The update itself never deletes a file, so files you added yourself are never removed. - Git-backed installs: the daily workflow lands each update as a merge commit.
git logshows it andgit revert -m 1 <merge-commit>undoes it. Git then treats those upstream changes as already merged, so later syncs will not bring them back until you revert that revert. Rannpm run updateyourself, on a clone or a local copy of your fork? Right after it,git reset --hard ORIG_HEADtakes the code back andnpm installrestores the previous dependencies. Migrations already applied stay applied. - A conflict behaves differently by install, on purpose. On a fork or clone the upstream merge is aborted and your working tree is left exactly as it was. On a standalone project the conflict is left in place for you to resolve — it is your own repository, and that is the point — and
git reset --hard HEAD,git clean -fdandnpm installback the whole update out. - A failed migration rolls back. Fix the cause and re-run; nothing half-applied is left behind.
- Unresolved conflicts hold the database back. If a merge left conflicts, the update finishes the code and dependency work but stops before migrating — your schema never moves ahead of code you have not finished deciding on. Resolve them and run
npm run updateagain to apply the migrations, or walk away withgit reset --hard HEAD,git clean -fdandnpm install; either way the database was never touched. Skip the last two and the new migration files stay on disk, where a later update or rebuild can apply them.
If you have customised a file that NextBlock owns — something under app/, components/ or lib/ — your edit is kept. The update merges the upstream change into your version, and only a change that genuinely overlaps yours conflicts — the updater lists those files, and each one carries ordinary <<<<<<< your version / >>>>>>> NextBlock markers. Edit them as you would any conflict, or run git checkout -- <file> to discard the merge for that one file. Customisations in your own files or in .env are never touched at all.
Knowing when there is something to update
You do not have to poll. NextBlock checks in the background while you use the CMS and raises a dashboard banner when a newer version is published, telling you which version you are on and what is available. Projects made with npm create nextblock get this banner, including sites built by an AI agent. One-click deploys and forks on Vercel do not, because the daily workflow merges updates for them. Administrators can also just run npm run update:check at any time.
Update FAQ
Will updating overwrite my content or settings?
No. Content, media, users and settings live in your database; site configuration lives in your environment variables. The update changes application code, dependencies and the database schema. A few migrations also make targeted data fixes, mostly to the demo content, translations and theme colours NextBlock seeded (see What happens to your database). None of them deletes your content.
Do I have to update every release?
No, though staying close to the latest release keeps you on security fixes and makes each jump smaller. Updates apply in sequence, so skipping several versions still lands correctly.
Can I run it in CI?
Yes — npm run update -- --yes never prompts, and it exits non-zero if the schema step fails so a pipeline can catch it. Setting CI=true also skips the prompts, in any shell.
What if my project has no database connection configured?
Code and dependencies still update; the schema step is skipped with a warning telling you which environment variable to set. Re-run npm run update -- --db-only once it is configured.
I deployed to Vercel, but from npm create nextblock. Is that automatic too?
No — and this is the distinction that catches people out. Automatic updates depend on your repository being the NextBlock monorepo, not on where the site is hosted. A project scaffolded by the CLI is the flattened standalone app whatever you deploy it to, so it updates with npm run update. You will not see the Connect GitHub step on that kind of install, because the workflow it installs would merge a completely different source tree into yours.
I am on the one-click Vercel deploy — do I need to run anything?
No command. Once the dashboard’s Connect GitHub step is green, that path is fully automatic. To update now rather than at midnight, open your repository’s Actions tab and click Run workflow under NextBlock Upstream Sync. Or run the command on a local clone and push.
One command, every install.
New to NextBlock? Start with the install guide — then never think about upgrades again.