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 of the four install paths 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 reports exactly what would change and touches nothing.
The four install paths, and how each one gets updates
These map one-to-one onto the four options in the install guide. The command is the same everywhere; what differs is where the new code comes from.
Fully automatic
One-click Vercel & GitHub forks
A daily workflow merges upstream into your repository and Vercel redeploys. You do nothing.
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.
1. One-click Vercel and GitHub forks — hands-off
This path updates itself. When you deployed, NextBlock 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.
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/.
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 updateIn 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.
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. |
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 change structure — tables, columns, indexes, permissions. Your pages, posts, products, media and users are yours; the update never deletes or rewrites them.
Belt and braces
Before a big jump on a production site, take a database snapshot — Supabase does daily backups on paid plans, and you can trigger one on demand from the Supabase dashboard. Then run npm run update -- --check to see the pending list 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 diff, and undo the whole thing withgit reset --hard HEAD. Nothing is ever deleted, so files you added yourself are never removed. - Git-backed installs: the update is an ordinary commit.
git logshows it andgit revertundoes it. - 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 HEADbacks 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; either way the database was never touched.
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, in the CMS, 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. 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 touches application code, dependencies and schema structure only.
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.
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. That path is fully automatic. The command exists for when you want an update now rather than at midnight, or when you are working on a local clone.
One command, every install.
New to NextBlock? Start with the install guide — then never think about upgrades again.