It is a fair question, and it gets sharper when the project touches regulated data, external partners, customer accounts, contractual availability or eventual integration with internal enterprise systems. We are two people. There is no sales department, no layer of account management, no bench of junior developers to absorb a departure, no internal infrastructure team.

The tempting answer is to inflate. Talk about "the team", describe capabilities in the passive voice, let the buyer imagine an organisation that does not exist. I have watched that approach work in procurement and then fall apart in delivery.

The answer we give instead is a division of responsibility. We stay directly accountable for product direction, user experience, application architecture, implementation, data and integration design, and the quality of what ships. For infrastructure, platform security, availability, framework-level support and independent security validation, we work with specialist vendors and, where it matters, with the companies that build and operate the underlying technology.

A small senior team delivers the product. Enterprise technology vendors support the platform. The client retains control.

This article is not an argument that two people are better than fifty. It is an explanation of how a small senior team can structure responsibility in a way that survives serious enterprise scrutiny.

The concern is legitimate

Enterprise software is not evaluated by asking whether the supplier can write the code. A buyer has to think about capacity, about what happens if a key person becomes unavailable, about who operates the infrastructure and who answers the phone during a platform incident. They need to know how security updates are handled, whether availability commitments can be met, whether an external specialist can review the implementation, whether the client can take control if the relationship ends, and whether the platform can keep evolving for years.

Those are operational questions, and a polished demonstration does not answer them. A demo proves a team understands the product and can build it. It does not eliminate long-term supplier risk.

I have written separately about procurement fit and why a strong product match does not always produce the right engagement, because alignment has to hold across the product, the delivery model and the buying process at the same time.

Headcount is an imperfect proxy

Companies use team size as a shortcut for operational stability, and the logic is understandable. Fifty employees look like more replacement capacity than two.

But headcount does not tell you who will actually work on your project, and it does not tell you who operates the systems underneath it. A larger agency may present its senior sales and strategy people during procurement and assign the work to a smaller implementation group once the contract is signed. That agency still depends on a public cloud provider, an identity provider, a managed database, third-party monitoring, an external penetration-testing company and a stack of open-source frameworks maintained by other organisations entirely.

Almost every modern software company runs on a network of vendors. So the useful question is not how many people the implementation company employs. It is who is responsible for each critical layer of the system, and what assurance exists around that responsibility.

That is the question we answer explicitly.

What we take responsibility for

We own the application and the product, which is the part you cannot buy by purchasing an Enterprise platform.

On product and experience, we work directly with stakeholders to define who the platform serves, which journeys matter, what belongs in the first release, how different audiences move through the system and where it expands later. There is no handoff from a sales consultant to a separate product team. The people in the room are the people designing and building it.

On architecture, we define the frontend and backend boundaries, the content and operational data models, system ownership, APIs and integrations, authentication and authorization, tenant and partner isolation, caching, analytics, deployment structure and the migration path forward. Where the project includes a CMS, we also decide what that CMS should not control. A flexible CMS can store almost anything, which is exactly why it quietly becomes the source of truth for business data it was never meant to own. I go deeper on that in CMS Architecture: Define What Your CMS Must Not Own.

On security, the line is worth stating plainly, because it is the one buyers most often blur: a managed hosting platform does not secure badly designed application code. The infrastructure provider secures the platform it operates. We secure the application running on it, which means authorization rules, role design, tenant isolation, input validation, API permissions, session handling, secrets, dependency updates, audit trails and the remediation of anything a security review finds in our implementation.

And we stay responsible for making the system understandable to someone who is not us. Architecture and data-flow documentation, deployment instructions, environment definitions, integration contracts, decision records, known limitations and open risks. Documentation is not a deliverable bolted on at the end of the project. For a small team it is one of the main mechanisms that reduces the client's dependency on us, which makes it a commercial artifact as much as a technical one.

What we deliberately do not rebuild

Some enterprise capabilities are expensive and difficult because they should be. Operating secure, resilient infrastructure takes continuous investment in networking, platform engineering, observability, incident response and security operations.

We have no interest in reproducing a global edge network, network-level DDoS protection, a proprietary web application firewall, multi-region orchestration, an internal 24-hour operations department, our own identity provider or a platform-wide observability product inside a project implementation budget. Those things already exist as managed Enterprise services, operated by organisations whose entire business is providing them.

This is not blind outsourcing. We still have to select, configure and integrate those services correctly, and getting that wrong is its own failure mode. The distinction is that the platform underneath is run by people who do nothing else.

The responsibility map

For a typical enterprise web platform, the model looks like this.

The exact services depend on the package selected and the client's requirements, but the shape holds. We remain responsible for the implementation; the vendor provides an escalation path to the people who maintain the framework itself. The security firm is deliberately not us, which creates separation between the company building the application and the company validating it. And the client never loses control simply because the work is delivered externally.

Why naming parties beats promising everything

There is a version of this conversation where every procurement requirement gets the same answer. WAF? Yes. Multi-region failover? Yes. Security monitoring, framework support, penetration testing, 24-hour incident response, long-term maintenance? Yes, yes, yes.

From a two-person company, that answer becomes difficult to believe somewhere around the third yes.

The stronger answer identifies the responsible party for each requirement. The implementation team owns authorization. The cloud platform owns the underlying infrastructure. The WAF provider operates perimeter protection. The framework vendor handles product-level escalation. An independent firm conducts the penetration test. The client's security team defines acceptance.

That replaces a broad promise with named responsibilities, contracts and escalation paths, which means the buyer can inspect the model rather than trust it. In enterprise delivery that is usually worth more than claiming one supplier internally owns every competency.

Buy the assurance you actually need

Enterprise support packages are expensive. A client may eventually need advanced platform support, a contractual 99.99% availability SLA, managed security rulesets, multi-region failover, private networking, extended log retention, directory synchronization, SIEM integration and formal architecture reviews.

That does not mean all of it has to be bought before the first user reaches the platform.

A secure MVP can start with approved EU hosting, HTTPS, managed backups, secure secret storage, role-based access, strong tenant isolation, application logging, dependency maintenance, baseline WAF and DDoS protection, monitoring, documented recovery procedures and an independent penetration test before production. The heavier Enterprise layers get activated when internal security policy, real traffic, a contractual commitment, a sensitive integration or a regulator requires them.

The principle is to design for the higher standard from the beginning but not to purchase every higher-cost capability before it is required. That avoids both failure modes: launching cheaply onto an architecture that has to be thrown away, and loading an unvalidated product with substantial annual vendor costs.

When those vendor costs do arrive, they should be visible. A proposal should separate architecture and discovery, product design and implementation, third-party and Enterprise platform costs, independent security services, and ongoing support. Keeping them separate shows the client what it is buying, stops us absorbing unpredictable vendor pricing, allows the client to contract directly with major vendors where that makes sense, and makes later upgrades easy to evaluate. A client asking for high-assurance infrastructure should expect the platform cost that comes with it. That number is not evidence of inefficient development. It is the price of the service level being requested.

Start with architecture, then scope milestones independently

None of this works until the requirements are actually understood. Before recommending an expensive Enterprise package, we need to know what data the platform will process, whether it must stay in the EU, which systems it integrates with, whether SSO is required, what availability is contractual, how long logs must be retained and whether they flow into an internal SIEM, who owns the hosting accounts, which vendors are already approved, who performs the penetration test, and whether the first release handles public information or sensitive applications.

That is why we recommend an architecture and discovery sprint before full implementation. It closes the decisions needed to build the first release safely and separates confirmed requirements from assumptions and from things that belong to a later phase. For complex projects this is far more reliable than treating the first mockups as a production specification, a point I make more fully in Website Rebuilds: Start with Architecture, Not Mockups. The sprint should end with confirmed V1 scope, an architecture recommendation, system boundaries, vendor decisions, security requirements, data ownership, an integration strategy, a roadmap, named risks, acceptance criteria and implementation pricing that means something.

After that, we work in independently scoped milestones rather than an open-ended multi-year commitment, because a small team promising unlimited parallel capacity is exactly the kind of claim that collapses later. A typical shape runs from architecture and discovery, to the core platform foundation of authentication, data models, environments and deployment, to the first complete customer journey, then partner and internal operations, then integrations, security testing and production hardening.

Each milestone defines its deliverables, responsibilities, timeline, price, acceptance criteria, dependencies, handover state and the decisions we need from the client. That gives the client budget control, lets the architecture absorb real information as it arrives, and keeps the committed scope proportionate to the capacity of the people actually doing the work.

Prove it with working software

A small team cannot win on a capability deck. The strongest evidence available to us is a working vertical slice.

For a recent enterprise opportunity we demonstrated considerably more than frontend screens. The concept included the customer-facing journey, an AI-guided experience, the workflow operating behind that AI, structured application data, analytics and session replay, partner administration, internal CMS administration, and the architecture and security documentation underneath. The point was not to pretend the production system existed. It was to show that the visible experience connected to a credible implementation model.

I go further into that idea in A Software Demo Should Show the System, Not Just the Screen.

This matters more for us than for a large supplier. An agency can point at headcount, departments and twenty years of corporate history. A specialist team has to make its capability visible in the work itself, and the people presenting the system have to be the people who understand how it works.

Client control matters more when the supplier is small

A client should never be trapped by an implementation partner. That is true of any supplier and it deserves particular attention with a two-person one.

So we structure projects so the client holds access to the source repository, ownership or administrative access to infrastructure accounts, access to deployment environments, documented secrets procedures, architecture documentation, integration specifications, data exports, deployment and rollback instructions, clear licensing information and a handover point at every milestone. Where it is practical, the client contracts directly with the major Enterprise vendors.

That produces a healthier relationship than dependency does. The client keeps working with us because the collaboration is worth something, not because leaving would make the system inaccessible.

What this model does not fix

It does not make us equivalent to a fifty-person agency. Product and implementation knowledge is still concentrated in very few people. Documentation, narrow commitments, phased delivery, vendor support, client access and independent review all reduce that concentration. None of them removes key-person risk entirely, and I am not going to claim otherwise.

A client whose procurement policy requires a large interchangeable internal workforce, several parallel development squads, 24-hour application support delivered by the implementation company itself, or on-site staffing should probably choose a different kind of provider. That is a legitimate decision, and the model works best for clients who value direct access to senior people, fast technical decisions, few communication layers, architecture built for their actual business and the ability to get from concept to working software quickly.

The goal is not to make every enterprise buyer compatible with how we work. It is to describe the model clearly enough that both sides can judge the fit honestly and early.

Small does not have to mean unsupported

Size matters. It affects capacity, operational concentration and how a buyer weighs risk, and pretending otherwise is the fastest way to lose credibility in a procurement conversation.

But size is not the only source of assurance. Direct senior accountability, working evidence, realistic commitments, phased delivery, complete documentation, managed infrastructure, direct vendor support, independent security validation and genuine client control are all sources of assurance too, and most of them are things a small team can offer more reliably than a large one.

So we do not try to run a traditional agency in miniature. We focus on the product and the application, use managed Enterprise platforms for infrastructure, bring in the companies behind the technologies when direct vendor assurance is required, let independent specialists validate the security, and keep the client in control of the result.

That is how two people approach serious enterprise software responsibly. Not by promising that two people can do everything, but by making sure the right party is responsible for every important part.

Let me know in the comments if you have questions, and subscribe for more practical development guides.

Thanks, Matija

I went with FreeCrawl, an open-source crawler that runs from the command line, stores everything in a local SQLite database and renders JavaScript through Playwright. It worked. The crawl recovered 1,625 HTML pages, 92,071 internal link relationships and a 441 MB database.

It also failed in three places that cost me a full crawl, and none of those failures are in the documentation. This guide walks through the installation and crawl sequence that actually worked, the two commands that did not, and how to read the crawl database while the crawler is still running.

What I ran it on

The workflow below was verified on a MacBook Pro, macOS 15.7.1, Apple Silicon, 10 cores and 16 GB of memory, with Node.js 24.12.0, npm 11.6.2 and Git 2.52.0. FreeCrawl ran CLI-only against commit b91a2b7eae32f0688b11a62a0ce954beea0813df. The Electron desktop application was never opened, Docker was never touched, and JavaScript rendering used Playwright Chromium in true headless mode.

That distinction matters for the Ubuntu section near the end. The macOS path is tested. The Linux path is reasoned from the project structure, not verified.

Installing from source

There is no packaged release in this workflow. You clone the repository and build it yourself, so start by confirming your toolchain is present.

node --version
npm --version
git --version

The project declares Node.js 22 or newer. Node 24 worked without complaint.

git clone https://github.com/kemalai/FreeCrawl-SEO-Tool.git
cd FreeCrawl-SEO-Tool
npm install

Keep the crawler outside the repository you are auditing. It pulls in its own build output and browser binaries, and there is no reason for Chrome for Testing to end up in a client project.

That npm install is heavier than it looks. The post-install script downloads Chrome for Testing, Chrome Headless Shell and FFmpeg, and the installed footprint came to roughly 1.9 GB before a single URL was crawled: about 1.4 GB for the repository, build output and dependencies, and another 534 MB for the Playwright browser cache.

The install also reported 18 npm vulnerabilities, one of them critical. I did not investigate them, so I cannot tell you whether they were exploitable in this context. If you are putting this on a shared or production server, read the report yourself before deciding how to isolate the tool.

npm audit

Do not reflexively run npm audit fix here. Review the proposed dependency changes first.

The build order the docs do not mention

The obvious command is the one that fails.

npm run build:cli

From a clean clone, that produced module resolution errors:

Cannot find module '@freecrawl/shared-types'
Cannot find module '@freecrawl/core'
Cannot find module '@freecrawl/db'

FreeCrawl is a TypeScript monorepo, and the CLI package depends on shared packages that have not been compiled yet. Running the TypeScript project build first resolves every one of those errors.

npx tsc -b
npm run build:cli
node apps/cli/dist/index.js --help

So the complete installation, from nothing to a working binary, is this:

git clone https://github.com/kemalai/FreeCrawl-SEO-Tool.git
cd FreeCrawl-SEO-Tool
npm install
npx tsc -b
npm run build:cli
node apps/cli/dist/index.js --help
git rev-parse HEAD

That last line is worth keeping. FreeCrawl is under active development, and recording the commit means you can tell later whether a behavior change came from the tool or from your own configuration.

The external-link behavior that cost me a crawl

My first production crawl went in the bin because FreeCrawl started making real requests to social-sharing and citation domains that appeared in the page content.

The --external flag reads as though it governs whether external URLs are requested at all. It does not. In the tested version, FreeCrawl made one real status-check request to every discovered external URL whether or not the flag was passed. What the flag controls is whether the crawler then continues recursively through those external pages. I only confirmed this by reading the crawler source after foreign hostnames turned up in the database.

The fix is an explicit exclusion pattern that allows your domain and blocks everything else.

--exclude "^https?://(?!(www\.)?example\.com([:/]|$))"

That negative lookahead permits https://example.com/ and https://www.example.com/ and rejects any other host. Add it to every single invocation. Configuration does not carry over between commands, so a crawl you run tomorrow without the flag will start hitting third-party domains again.

Run twenty URLs before you run twenty thousand

A ten to twenty URL test crawl would have caught the external-domain problem in under a minute, which is the main reason this section exists.

mkdir -p output/example

node apps/cli/dist/index.js \
  https://example.com/ \
  --depth 2 \
  --max 20 \
  --concurrency 2 \
  --rps 1 \
  --exclude "^https?://(?!(www\.)?example\.com([:/]|$))" \
  --db output/example/test.seoproject

Replace both instances of example.com with the domain you are authorized to crawl. Then open the resulting database and check which hosts were actually requested, whether images and scripts are being stored, whether query parameters are generating duplicate URLs, and whether the site is returning throttling responses. Only move on once the scope is provably correct.

While you are here, read the robots file properly rather than assuming.

curl -fsSL https://example.com/robots.txt

The production site I crawled declared a very high crawl delay. The crawl was authorized by the site owner, so we agreed on a conservative two requests per second instead, and the corrected run returned no 429, 502 or 503 responses at all. Without that authorization, respect what is published.

Sitemaps are worth locating at the same time, because a link-following crawl and a CMS-generated sitemap answer two different questions. The crawl finds pages reachable through links. The sitemap lists URLs the site claims should exist. The gap between them is where orphan pages, stale URLs and navigation holes live, which is exactly what a migration inventory needs.

curl -I https://example.com/sitemap.xml
curl -I https://example.com/sitemap_index.xml
curl -I https://example.com/wp-sitemap.xml

A 200, 301 or 302 response tells you a URL responds, not that it contains valid XML. Download it and look at it.

The primary raw HTML crawl

With scope confirmed, the real run is the same command with the limits opened up and exports requested.

node apps/cli/dist/index.js \
  https://example.com/ \
  --depth 20 \
  --max 100000 \
  --concurrency 4 \
  --rps 2 \
  --exclude "^https?://(?!(www\.)?example\.com([:/]|$))" \
  --db output/example/example-text.seoproject \
  --out output/example/example-text.json \
  --json

The depth of 20 lets the crawler follow deeply nested internal paths, and the 100,000 ceiling replaces the artificial 500-URL limit that sent me here in the first place. Concurrency and requests per second are the two politeness controls, and raising concurrency does nothing useful when the rate limit or the origin server is the real bottleneck, so start low. The --db flag writes the SQLite project, and --out plus --json request an export and a machine-readable summary once the crawl finishes naturally.

That last condition matters more than it sounds. I will come back to it.

A URL count is not a page count

The crawl reached 5,554 internal URLs. Only 1,625 of them were pages.

FreeCrawl records linked resources in the same table as documents, so a headline number like "5,554 URLs crawled" will quietly inflate your migration scope by a factor of three if nobody separates them. For a content migration, treat HTML and PDFs as documents and everything else as resources. The resource count still matters for media analysis, but it is not the page inventory.

Querying the crawl database

The .seoproject file is an ordinary SQLite database, and this turned out to be the single best thing about the tool. Instead of being limited to whatever reports someone decided to build, every question I had became a query.

brew install sqlite
sqlite3 output/example/example-text.seoproject

Start with the same breakdown as above, straight from the database.

SELECT
  content_kind,
  COUNT(*) AS total
FROM urls
WHERE is_external = 0
GROUP BY content_kind
ORDER BY total DESC;

Filtering on is_external = 0 is your check that the exclusion rule held. If foreign hostnames appear anywhere in this table, the crawl scope leaked and the run is not trustworthy.

From there, the audit questions are all variations on filtering content_kind = 'html'.

SELECT
  status_code,
  COUNT(*) AS total
FROM urls
WHERE content_kind = 'html'
GROUP BY status_code
ORDER BY status_code;

SELECT
  url
FROM urls
WHERE content_kind = 'html'
  AND status_code = 200
  AND (title IS NULL OR TRIM(title) = '');

SELECT
  title,
  COUNT(*) AS occurrences
FROM urls
WHERE content_kind = 'html'
  AND status_code = 200
  AND title IS NOT NULL
  AND TRIM(title) <> ''
GROUP BY title
HAVING COUNT(*) > 1
ORDER BY occurrences DESC;

Missing titles come from a null-or-empty check restricted to successful HTML responses, so redirects and errors do not pollute the result. Duplicate titles come from grouping the same filtered set and keeping only the groups with more than one member. Neither needs an export step, and both can be rerun against the database a month later when someone asks whether the problem was fixed.

The database is also readable while the crawler is still writing to it, which is how I worked out when to stop.

SELECT COUNT(*) FROM crawl_queue;

Watching the HTML count sit still at 1,625 while thousands of image requests remained queued told me the page discovery was finished and the remaining work was resources I did not need.

Read the links table, not the convenience columns

FreeCrawl stores the discovered link graph in a links table, which held 92,071 internal relationships in my crawl. The urls table also has an inlinks column, and mine was zero across the board, because that column is populated by an end-of-crawl aggregation step that never ran.

If you interrupt a crawl, calculate from the raw graph instead.

SELECT
  to_url,
  COUNT(*) AS inlinks
FROM links
WHERE is_internal = 1
GROUP BY to_url
ORDER BY inlinks DESC;

The more useful version joins that graph against response status, which gives you every broken page ranked by how many internal links still point at it. That is your redirect priority list for a migration.

SELECT
  l.to_url,
  COUNT(*) AS internal_links
FROM links AS l
JOIN urls AS u
  ON u.url = l.to_url
WHERE l.is_internal = 1
  AND u.status_code >= 400
GROUP BY l.to_url
ORDER BY internal_links DESC;

A static export cannot answer that question without a script. A relational link graph answers it in six lines.

Stopping early changes what you get

I stopped the primary crawl deliberately, once HTML discovery had plateaued and the queue was mostly images.

kill -INT <PROCESS_ID>

The process exited with code 130, which correctly signals an interrupt rather than a crash, and the SQLite database remained fully usable. Two things did not happen: the JSON export I requested with --out was never written, and the aggregate fields like inlinks were never populated.

The crawl was still successful. The pages, metadata and link graph were all there. The missing export was a consequence of how I ended the process, not evidence of failure.

Treat the SQLite database as the primary artifact and the JSON as a bonus you only trust when the process exits on its own.

Exit codes need the same skepticism. During one JavaScript sample run, FreeCrawl returned exit code 1 simply because the crawl had encountered HTTP error responses, and the database and summary were both complete. If you are wrapping this in automation, check whether the database exists, how many rows it holds and what the status summary says, rather than treating any non-zero exit as an unusable crawl.

Test JavaScript rendering on a sample

A browser-rendered crawl is far more expensive than a raw HTML one, so the question is not whether FreeCrawl can render JavaScript but whether your site needs it.

Put a representative set of URLs in a plain text file at output/example/js-sample-urls.txt:

https://example.com/
https://example.com/products/example-product/
https://example.com/blog/example-article/
https://example.com/recipes/example-recipe/
https://example.com/category/example/

Then a config file at output/example/js-config.json:

{
  "renderingMode": "js",
  "maxDepth": 0,
  "maxUrls": 250,
  "maxConcurrency": 2,
  "maxRps": 1,
  "respectRobotsTxt": true,
  "crawlExternal": false,
  "jsRender": {
    "headless": true
  }
}

The maxDepth of 0 is the important line. It tells FreeCrawl to render exactly the URLs in your list and not follow links out of them, which keeps an expensive rendering pass from turning into a second full crawl.

node apps/cli/dist/index.js \
  --list output/example/js-sample-urls.txt \
  --config output/example/js-config.json \
  --exclude "^https?://(?!(www\.)?example\.com([:/]|$))" \
  --db output/example/js-sample.seoproject \
  --out output/example/js-sample.json \
  --json

I compared 39 URLs this way, covering the homepage, navigation pages, products, blog posts, recipes, taxonomy pages and anything likely to contain interactive elements. Chromium launched in true headless mode without any display server, and across all 39 pages the rendered crawl found no meaningful difference in titles, meta descriptions, H1s, canonicals, hreflang counts, structured data types, link counts or word counts.

That is not a rendering failure. It is evidence that this particular WordPress site already served every migration-relevant field in its initial HTML, which meant a full JavaScript crawl would have cost hours and told me nothing new. Crawl raw HTML first, render a sample, compare, and only escalate if the sample shows you something missing.

What the crawl actually produced

For the record, here is what came out of the corrected production run.

Alongside that, it flagged 474 missing titles, 399 duplicate titles, 699 missing meta descriptions, 588 missing H1s, 691 pages with multiple H1s, 1,113 sitemap-only URLs and 607 crawled URLs absent from the sitemaps.

Those numbers prove FreeCrawl can build a real inventory. They do not prove that every line is a defect. Archive pages, redirects, utility routes and deliberately non-indexable content can legitimately lack the metadata you would demand of a landing page. A crawler produces candidates, and the audit still needs a human deciding which ones matter.

The other boundary is worth stating plainly, because it caught a colleague out on a previous project. A public crawl tells you which URLs are reachable, which are declared, how pages link to each other and what metadata renders. It cannot tell you which WordPress post type owns a URL, which custom fields produced the page, which drafts and private records exist, which page-builder components were used or which translations are incomplete. For a migration you need the crawl and a database or API export from the CMS. One is the external view, the other is the source of truth.

Running it on a server

Ubuntu Server was not part of this implementation, so treat the following as a path to test rather than a confirmed reproduction.

sudo apt-get update
sudo apt-get install -y curl git ca-certificates

curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

git clone https://github.com/kemalai/FreeCrawl-SEO-Tool.git
cd FreeCrawl-SEO-Tool

npm install
sudo npx playwright install-deps chromium

npx tsc -b
npm run build:cli

node apps/cli/dist/index.js --help

The one addition over the macOS sequence is playwright install-deps chromium, which pulls the system libraries Chromium needs on Linux. Because Playwright Chromium supports genuinely headless execution, this should not require GNOME, VNC or any visible browser session. On a shared machine I would also run it under a dedicated non-root user, keep it well away from application repositories, restrict outbound network access and preserve crawl databases somewhere that is not a temporary directory.

What I would tell you before you start

FreeCrawl is genuinely usable as a free Screaming Frog alternative, provided you are the kind of person who is comfortable with a terminal, a regular expression, a SQL query and occasionally reading source code when the documentation runs out. The absence of a URL limit and the presence of a queryable database made it a better fit for a developer-led migration than a graphical application would have been.

Three things will bite you, and all three are avoidable now that you know about them. The CLI build fails from a clean clone unless you run npx tsc -b first. External domains get status-checked unless you exclude them explicitly on every command. And an interrupted crawl silently skips the JSON export and the aggregate columns, so the SQLite file is the artifact you should trust.

Use Screaming Frog when you want a mature, polished application and an interface that a non-technical colleague can operate. Use FreeCrawl when you want a crawler you can automate, inspect and query as part of a technical workflow. For the migration inventory I needed, the second was worth more than the first.

Let me know in the comments if you have questions, and subscribe for more practical development guides.

Thanks, Matija

I ran into this recently while presenting for a regulated financial-services client. An earlier session had covered the customer-facing concept alone. For the follow-up, we expanded the demonstration to include the revised user journey, an AI guide, the automation workflow running behind it, the underlying vehicle data, behavioural analytics, partner administration, the internal CMS, and documentation covering architecture, hosting, and security. The reaction was noticeably stronger than the first session — not just because the visuals had improved, but because the client could see how the platform might actually operate once it existed.

Why a polished frontend is only proof of design intent

The frontend is the natural starting point for any demo. It's where the customer, employee, or partner experiences the product, and it can show where users begin, how they navigate, which information gets emphasis, and how a multi-step journey behaves across its stages.

A working frontend prototype demonstrates real things: where users start, how they search, which choices get simplified, how different audiences enter the platform, and how the experience might expand later. Many software problems are interface problems at heart, and a confusing journey stays confusing no matter how clean the architecture behind it is.

That evidence covers one layer. A screen showing a monthly payment doesn't explain where the calculation comes from. An AI assistant recommending a product doesn't reveal whether it's pulling from trusted data or generating a plausible guess. A partner dashboard doesn't show whether partners are properly isolated from each other. A content-management screen doesn't identify which system actually owns the underlying information. Answering those questions is the job of the layers behind the interface.

This connects to a distinction I've written about before: a prototype contributes to an implementation specification — it doesn't stand in for one. A sales demo doesn't need the full specification yet. It needs enough evidence that a plausible implementation sits behind the interface.

Layer 1: Anchor the demo in one customer journey

Start the demo with a realistic scenario rather than a set of unrelated screens.

Instead of demonstrating a generic vehicle marketplace, follow one customer: someone who needs a second family vehicle, has a maximum budget, owns a vehicle they could trade in, is considering an electric model, has questions about battery life and service availability, and wants to understand the monthly cost.

Every part of the demo now has a reason to exist. The search experience addresses the budget. The AI guide addresses the uncertainty about batteries and service. The vehicle detail page covers product information. The calculator addresses affordability. The application step covers the commercial outcome.

A connected scenario like this gives stakeholders a real basis for judging whether the platform solves a problem, and it exposes gaps that a set of individually polished screens can hide. Before moving behind the interface, the journey should answer five questions: what the person is trying to accomplish, what the platform needs to learn from them, how it helps them decide, where the journey leads, and what happens after the final call to action.

Layer 2: Show the business logic behind the interaction

The next layer is the logic controlling what the customer sees, and this matters most where the interface includes AI.

An AI chat window is simple to add to a prototype and easy to misjudge. The questions worth answering aren't about how fluently the assistant writes — they're about what it can access, which actions it can perform, how it queries the platform, which calculations stay deterministic, which rules constrain its recommendations, what gets logged, and where a human or a controlled system takes over when the model is uncertain.

In our demo, the frontend AI guide connected to an automation workflow with identifiable steps: interpret the request, determine what information is missing, ask a follow-up question, convert the answer into structured values, query trusted platform data, apply constraints, assemble the response, record the interaction, and trigger the next action when appropriate.

The customer experienced a natural conversation. Showing the steps behind it reframed the demo from "the chatbot can answer questions" into a working example of natural language acting as another interface into controlled platform services — which is the distinction that matters in any serious AI project. Product data, pricing rules, permissions, financial calculations, and business actions should live in systems that can be validated and audited, with the language model handling interpretation and conversation on top of them. A useful demo makes that boundary visible.

Layer 3: Show where the data actually lives

Once the business logic is visible, show the data feeding it. This doesn't require the full database schema — it requires proving that important information has a defined home.

Our vehicle records carried structured fields: make and model, price, powertrain, battery capacity, estimated range, battery condition, financing attributes, partner ownership, and publication status. When the AI guide answered a question about a specific vehicle, we opened the admin interface and pointed to the corresponding stored value. That small step turns an answer that sounds convincing into one that's traceable back to a record someone can inspect.

The same principle travels outside automotive platforms. A healthcare site recommending content by health goal should be able to show where the approved health-goal relationships live. A manufacturing portal displaying specifications should show whether they come from the CMS, ERP, PIM, or elsewhere. A customer dashboard displaying account status should show which operational system owns that state. This is also the reasoning behind deciding upfront what the CMS must not own — a flexible CMS can store almost anything, which is exactly why its scope needs a boundary. The demo doesn't need to settle every ownership question, but it should show the boundaries have been considered.

Layer 4: Show how the platform gets operated

Most software demos focus entirely on the customer, and the platform still needs someone to run it after launch — internal editors, account managers, marketplace partners, administrators, support staff, compliance reviewers, product managers, analysts.

Customers browsing listings is only part of a marketplace; someone still has to create, import, review, update, suspend, and remove those listings. An AI assistant answering questions is only part of the product; someone has to maintain its information, review failed interactions, and update its rules. Content rendering on a page is only part of a content platform; someone has to draft, approve, publish, translate, and retire it.

In our demo, we showed two separate admin experiences: a tailored partner workspace where a partner could sign in, see its own records, manage listings, and review its inquiries; and a broader platform admin environment where internal users managed content, vehicles, partners, users, roles, publishing states, and structured data. The separation communicates a design decision worth stating directly: different users get the interface suited to their responsibilities, even when both interfaces sit on the same platform. A partner doesn't need the full technical CMS. An editor doesn't need infrastructure controls. A platform administrator may need access across several domains at once.

Showing these operational views tends to unlock better implementation conversations — stakeholders start asking who approves a new partner, whether a dealer can publish directly, which changes require review, whether one partner can see another's leads, what happens when a listing expires, and which fields need an audit trail. Surfacing these production questions early, during the demo, is far cheaper than surfacing them during delivery.

Layer 5: Show how the team will measure behaviour after launch

A platform shouldn't go dark once it's live. The team needs visibility into where users arrive, which journeys they choose, where they hesitate, what they search for, which features they use, where they abandon the process, and which interactions actually produce qualified inquiries.

Traditional web analytics covers acquisition sources, campaigns, and broad conversion numbers — useful for marketing, but only part of the picture. Product analytics tools such as PostHog add funnels, interaction events, feature adoption, session recordings, and the friction points that repeat across users.

In our demo, we replayed the session that had just happened. Stakeholders watched the journey, the scrolling, and the interaction with the AI guide play back in front of them. That's a stronger claim than promising "everything can be tracked" — it's showing exactly what a product team would be able to inspect after launch, tied to specific questions worth answering: do users prefer classic or guided search, which financing concepts create confusion, which products get attention without inquiries, and where do users leave the application journey.

Layer 6: Show the architecture and the operational controls behind it

The final layer explains how the demo becomes a production system, and it doesn't need to dominate the meeting — most stakeholders don't want thirty minutes on hosting topology and deployment pipelines. The information still needs to exist and be easy to reach.

We built a self-service documentation area covering the proposed technology stack, application architecture, CMS selection, hosting options, environments, authentication, permissions, integrations, security controls, secret management, backups, deployment, operational responsibilities, open decisions, and implementation risks. The goal wasn't to claim every architectural decision was final — it was to show the proposed solution had been thought through beyond the browser window.

This is where the demo connects naturally into discovery. Some decisions can be proposed during a demo; others depend on information only the client's technical, security, compliance, and operational teams can supply. The useful response to that gap is documenting the current assumption, its impact, and what needs validating before implementation — which is also why I generally recommend teams start with architecture rather than mockups alone on complex platform work. The interface and the architecture should inform each other, and structural decisions shouldn't get made by accident while developers are already building production features.

A self-service documentation environment gives every stakeholder group what they need from the same material: business stakeholders can stay focused on the journey, technical stakeholders can inspect the proposed stack, security teams can review controls and open questions, and future implementation partners can see the decisions already made.

Naming what's real and what's simulated

A demo where every button works, every response succeeds, every integration appears available, and every field is populated looks finished. It can also create false certainty about how much of the system actually exists.

A more credible demo separates what's already working from what's simulated, what uses synthetic data, what depends on an external integration still to be confirmed, what's a recommended direction versus a client-confirmed decision, and what still needs discovery or belongs in a later phase. An AI guide can be genuinely working while pulling from demonstration vehicle records. A trade-in valuation step can be interactive while the production version depends on an external provider not yet selected. A financing calculation can respond live while its final formula and regulatory wording still need approval. Stating these boundaries clearly makes the demo more trustworthy, not less — the goal is proving the proposed experience connects to a credible system and that the team knows what's still unresolved, not creating the illusion that the project is already finished.

A demo sets direction; discovery turns it into a contract

Showing more of the system doesn't mean finishing the architecture, specification, and implementation before the project starts. A demo proves capability and direction. Discovery turns that direction into an agreed delivery contract — confirming V1 scope, user journeys, system boundaries, integrations, data ownership, hosting, security requirements, roles and permissions, operational workflows, analytics, migration, testing, acceptance criteria, and later phases.

Getting the depth right here matters on both ends. A shallow demo leaves the client unsure whether the provider understands the full system. An oversized demo quietly does the discovery work for free before any contract exists. The right level sits between the two: enough depth to demonstrate connected thinking, followed by a paid process that resolves what implementation actually requires.

What each layer proves

Together these layers create a far stronger signal than a sequence of polished screens, though they still leave real questions open — they don't eliminate delivery risk, settle every integration, replace a security review, or confirm that the buyer and provider are a good commercial match. Those belong to the broader question of procurement and delivery fit. What this kind of demo does reliably is shift the conversation: stakeholders stop debating button sizes and start discussing data ownership, partner permissions, integration constraints, measurement, security, and the commercial path forward.

FAQ

Does a demo like this require production-grade infrastructure? No. It needs a vertical slice through the important layers — journey, logic, data, operations, analytics, architecture — using demonstration data and a documented set of assumptions, not a finished, scaled system.

How much of the demo should focus on AI specifically? Enough to show the workflow behind it: what the assistant can access, which actions it triggers, which calculations stay deterministic, and where a human or controlled system takes over. Fluent conversation alone isn't the evidence stakeholders need.

Isn't showing this much of the system just doing discovery for free? Only if the demo goes too far. The right scope demonstrates connected thinking and surfaces the right questions; it stops short of resolving scope, integrations, and acceptance criteria, which is what a paid discovery phase is for.

What's the risk of demoing only the frontend? Stakeholders can mistake interface polish for system readiness. A confusing or fragile system can sit behind a clean screen, and a demo that never goes past the screen won't surface that.

Should every demo include admin and operational views? For any platform someone will need to run after launch — which is most of them — yes. Skipping this layer tends to move basic operational questions (who approves what, who can see what) from the demo into delivery, where they're more expensive to answer.

Bringing it together

A credible software demo runs through six connected layers: the customer journey, the business logic behind it, the data it depends on, the interfaces that keep it running, the analytics that measure it, and the architecture that lets it go to production. None of this requires building the whole system before a contract exists — it requires choosing a slice that shows the thinking behind the interface, not just the interface itself. That's the difference between a demo that shows what a platform might look like and one that shows how it could actually work.

Let me know in the comments if you have questions, and subscribe for more practical development guides.

Thanks, Matija

I've built this pattern most recently on a multi-brand rebuild covering three separate consumer sites sharing one Payload instance. Each brand needed its own theme, navigation, and content, while editors across all three needed the same set of approved blocks to build pages without opening a pull request. That constraint is what pushed the architecture toward one shared route with tenant-aware queries, rather than a route per brand or a template per page type.

The habit this breaks

Developers arriving from WordPress, Drupal, or Craft CMS usually look for a template file per page type: page-about.php, page-contact.php, single-product.php. Developers already comfortable with Next.js often reach for the same instinct in App Router form: a folder per page, app/about/page.tsx, app/contact/page.tsx, app/services/page.tsx.

That instinct comes from CMS platforms where the CMS itself participates in template selection. A page record carries a template value — Default Page, Landing Page, Campaign Page — and the CMS picks a matching file out of the active theme. The rendering path runs from URL to router to page record to selected template to rendered HTML, with the CMS deciding which theme file executes.

Payload works from a different starting point. It's a code-first CMS installed directly into your Next.js application, and it stores structured content rather than owning a template layer. Routing and rendering stay in your Next.js code; Payload's job is to hand that code the data and configuration an editor set up.

The Pages collection

Here's a simplified version of the collection that backs the shared route:

// File: src/collections/Pages/config.ts
import type { CollectionConfig } from 'payload'

import { HeroBlock } from '@/blocks/Hero/config'
import { TextMediaBlock } from '@/blocks/TextMedia/config'
import { CardsBlock } from '@/blocks/Cards/config'
import { CallToActionBlock } from '@/blocks/CallToAction/config'
import { FAQBlock } from '@/blocks/FAQ/config'

export const Pages: CollectionConfig = {
  slug: 'pages',

  versions: {
    drafts: true,
  },

  admin: {
    useAsTitle: 'title',
  },

  fields: [
    {
      name: 'title',
      type: 'text',
      required: true,
      localized: true,
    },
    {
      name: 'slug',
      type: 'text',
      required: true,
      index: true,
    },
    {
      name: 'layout',
      type: 'blocks',
      localized: true,
      blocks: [
        HeroBlock,
        TextMediaBlock,
        CardsBlock,
        CallToActionBlock,
        FAQBlock,
      ],
    },
  ],
}

The field that matters here is layout. It's a blocks field, which means each page document stores an ordered array of block entries, and editors choose which blocks appear and in what order. Payload tags each entry with a blockType value matching the block's slug, which the frontend later uses to pick a renderer.

A Hero block definition looks like this:

// File: src/blocks/Hero/config.ts
import type { Block } from 'payload'

export const HeroBlock: Block = {
  slug: 'hero',
  interfaceName: 'HeroBlock',

  fields: [
    {
      name: 'heading',
      type: 'text',
      required: true,
      localized: true,
    },
    {
      name: 'description',
      type: 'textarea',
      localized: true,
    },
    {
      name: 'image',
      type: 'upload',
      relationTo: 'media',
    },
    {
      name: 'actions',
      type: 'array',
      maxRows: 2,
      fields: [
        {
          name: 'label',
          type: 'text',
          required: true,
          localized: true,
        },
        {
          name: 'href',
          type: 'text',
          required: true,
        },
      ],
    },
  ],
}

This config is the contract an editor sees in the admin UI: heading, description, an image upload, and up to two actions. Every field here becomes a piece of data the frontend can rely on being present in a predictable shape. The React implementation behind this contract is a separate concern, which is what the renderer below handles.

The block renderer

A page document's layout array needs one thing to turn into HTML: a lookup from blockType to a React component. That lookup is the entire job of the renderer.

// File: src/blocks/RenderBlocks.tsx
import { HeroBlock } from '@/blocks/Hero/Component'
import { TextMediaBlock } from '@/blocks/TextMedia/Component'
import { CardsBlock } from '@/blocks/Cards/Component'
import { CallToActionBlock } from '@/blocks/CallToAction/Component'
import { FAQBlock } from '@/blocks/FAQ/Component'

const blockRenderers = {
  hero: HeroBlock,
  textMedia: TextMediaBlock,
  cards: CardsBlock,
  callToAction: CallToActionBlock,
  faq: FAQBlock,
}

type RenderBlocksProps = {
  blocks: Array<{
    id?: string | null
    blockType: string
    [key: string]: unknown
  }>
  site: {
    id: string
    slug: string
  }
}

export function RenderBlocks({ blocks, site }: RenderBlocksProps) {
  if (!blocks?.length) {
    return null
  }

  return blocks.map((block, index) => {
    const Renderer =
      blockRenderers[block.blockType as keyof typeof blockRenderers]

    if (!Renderer) {
      console.warn(`No renderer registered for block: ${block.blockType}`)
      return null
    }

    return (
      <Renderer
        key={block.id ?? `${block.blockType}-${index}`}
        {...block}
        site={site}
      />
    )
  })
}

Add a new block type in the future, and this is the one file you touch to register it. The route calling RenderBlocks never needs an update, because it only ever passes through whatever layout array the page document contains.

The shared route

With the collection and renderer in place, the route itself stays small. Next.js App Router's optional catch-all segment, [[...slug]], matches the site root along with any number of nested path segments, which is exactly the shape a flexible Pages collection needs.

app/
  (frontend)/
    [locale]/
      [[...slug]]/
        page.tsx

// File: app/(frontend)/[locale]/[[...slug]]/page.tsx
import { notFound } from 'next/navigation'

import { RenderBlocks } from '@/blocks/RenderBlocks'
import { getPage } from '@/data/getPage'
import { resolveSiteFromRequest } from '@/sites/resolveSiteFromRequest'
import { SiteThemeProvider } from '@/sites/SiteThemeProvider'

type PageProps = {
  params: Promise<{
    locale: string
    slug?: string[]
  }>
}

export default async function Page({ params }: PageProps) {
  const { locale, slug } = await params

  const site = await resolveSiteFromRequest()

  const path = slug?.join('/') ?? 'home'

  const page = await getPage({
    siteID: site.id,
    locale,
    path,
  })

  if (!page) {
    notFound()
  }

  return (
    <SiteThemeProvider site={site}>
      <RenderBlocks blocks={page.layout} site={site} />
    </SiteThemeProvider>
  )
}

Note the await params — current App Router versions deliver dynamic route parameters asynchronously, so that await is required, not optional. Beyond that, the route's job is five lookups: resolve the tenant, read the locale, join the slug segments into a path, fetch the matching document, and hand its blocks to the renderer. There's no branching on which page this is. The document coming back from getPage already carries everything the renderer needs.

Fetching the page document

getPage runs on Payload's Local API, which supports collection queries, locale and fallback-locale handling, relationship depth, and access control in a single call:

// File: src/data/getPage.ts
import { getPayload } from 'payload'

import config from '@payload-config'

type GetPageArgs = {
  siteID: string
  locale: string
  path: string
}

export async function getPage({ siteID, locale, path }: GetPageArgs) {
  const payload = await getPayload({ config })

  const result = await payload.find({
    collection: 'pages',
    locale,
    fallbackLocale: false,
    draft: false,
    limit: 1,
    depth: 2,
    where: {
      and: [
        {
          tenant: {
            equals: siteID,
          },
        },
        {
          slug: {
            equals: path,
          },
        },
      ],
    },
  })

  return result.docs[0] ?? null
}

For deeper page trees you'll usually want a dedicated path field instead of a bare slug — something that can hold values like about/our-story or campaigns/summer/wellness-guide — plus draft preview support, redirects, and caching on top of this base query. The lookup itself always reduces to the same equation: tenant plus locale plus path resolves to one page document.

Running this across multiple brands

This pattern earns its keep on a multi-brand platform. Take three sites sharing one Payload instance: canprev.ca, cytomatrix.ca, orangenaturals.com. A request to https://canprev.ca/en/about resolves to tenant canprev, locale en, path about. A request to https://cytomatrix.ca/en/about resolves to tenant cytomatrix, same locale, same path. The route handling both requests is the same file. What differs is the document getPage returns, and the theme SiteThemeProvider applies around it.

Payload's official multi-tenant plugin handles the tenant relationship side of this: it adds tenant fields to your configured collections and scopes both frontend queries and admin-panel visibility by tenant.

All three brands can draw from the same block library — Hero, Text and Media, Cards, Call to Action, FAQ, and so on — because a block's data contract stays constant across tenants even when its visual output changes. A HeroBlockData shape of heading, description, image, and actions works identically whether the brand wants rounded imagery and green accents or clinical typography and blue accents. Most of that variation lives in CSS variables and design tokens rather than in separate block definitions:

// File: src/sites/SiteThemeProvider.tsx
export function SiteThemeProvider({
  site,
  children,
}: {
  site: Site
  children: React.ReactNode
}) {
  return (
    <div
      data-site={site.slug}
      style={
        {
          '--brand-primary': site.theme.primaryColor,
          '--brand-secondary': site.theme.secondaryColor,
          '--font-heading': site.theme.headingFont,
          '--radius-card': site.theme.cardRadius,
        } as React.CSSProperties
      }
    >
      {children}
    </div>
  )
}

A shared Hero component reads those tokens directly:

// File: src/blocks/Hero/Component.tsx
export function HeroBlock({
  heading,
  description,
  image,
  actions,
}: HeroBlockData) {
  return (
    <section className="bg-[var(--brand-primary)]">
      <div className="site-container">
        <h1 className="font-[var(--font-heading)]">{heading}</h1>
        {description && <p>{description}</p>}
        {/* Image and actions */}
      </div>
    </section>
  )
}

When a brand's visual requirements go past what tokens can express, the block implementation can route to a tenant-specific presentation while keeping one Payload block definition:

// File: src/blocks/Hero/Component.tsx
const heroPresentations = {
  canprev: CanPrevHeroPresentation,
  cytomatrix: CytomatrixHeroPresentation,
  'orange-naturals': OrangeNaturalsHeroPresentation,
}

export function HeroBlock({
  site,
  ...block
}: HeroBlockData & { site: Site }) {
  const Presentation =
    heroPresentations[site.slug as keyof typeof heroPresentations] ??
    DefaultHeroPresentation

  return <Presentation {...block} />
}

Editors across every tenant still configure the same hero block in the admin panel. The tenant-specific React path is an internal detail of that one block's implementation.

Where a dedicated route is the right call

A shared Pages route handles free-form editorial content well, and it's a poor fit for content with a fixed, predictable structure. Products, recipes, events, and giveaways are the common examples — each has a stable set of fields an editor fills in, rather than a stack of blocks they arrange freely.

A recipe typically has title, description, prep time, cook time, servings, ingredients, instructions, dietary tags, related products, an author, and a featured image — a shape that stays constant across every recipe on the site. That belongs in its own collection with its own route:

// File: app/(frontend)/[locale]/recipes/[slug]/page.tsx
import { notFound } from 'next/navigation'

import { RecipeTemplate } from '@/templates/Recipe'
import { getRecipe } from '@/data/getRecipe'
import { resolveSiteFromRequest } from '@/sites/resolveSiteFromRequest'

type RecipePageProps = {
  params: Promise<{
    locale: string
    slug: string
  }>
}

export default async function RecipePage({ params }: RecipePageProps) {
  const { locale, slug } = await params

  const site = await resolveSiteFromRequest()

  const recipe = await getRecipe({
    siteID: site.id,
    locale,
    slug,
  })

  if (!recipe) {
    notFound()
  }

  return <RecipeTemplate recipe={recipe} site={site} />
}

RecipeTemplate composes existing blocks into a fixed order rather than reading an editor-defined layout array:

// File: src/templates/Recipe.tsx
import { RecipeHeroBlock } from '@/blocks/RecipeHero/Component'
import { RecipeMetaBlock } from '@/blocks/RecipeMeta/Component'
import { RecipeIngredientsBlock } from '@/blocks/RecipeIngredients/Component'
import { RecipeInstructionsBlock } from '@/blocks/RecipeInstructions/Component'
import { RelatedProductsBlock } from '@/blocks/RelatedProducts/Component'
import { FAQBlock } from '@/blocks/FAQ/Component'

export function RecipeTemplate({
  recipe,
  site,
}: {
  recipe: Recipe
  site: Site
}) {
  return (
    <>
      <RecipeHeroBlock
        title={recipe.title}
        description={recipe.description}
        image={recipe.image}
        site={site}
      />
      <RecipeMetaBlock
        preparationTime={recipe.preparationTime}
        cookingTime={recipe.cookingTime}
        servings={recipe.servings}
        site={site}
      />
      <RecipeIngredientsBlock ingredients={recipe.ingredients} site={site} />
      <RecipeInstructionsBlock instructions={recipe.instructions} site={site} />
      <RelatedProductsBlock products={recipe.relatedProducts} site={site} />
      {recipe.faq?.length > 0 && <FAQBlock items={recipe.faq} site={site} />}
    </>
  )
}

The building blocks here — RecipeHero, RecipeMeta, RecipeIngredients — are the same kind of reusable presentation units as the Pages collection's blocks. The difference is who controls their order: an editor arranges blocks freely on a Pages document, while a template fixes the arrangement in code for a structured content type.

Terminology worth keeping straight

Three words get used loosely on projects like this, and mixing them up causes real confusion between design and engineering:

Block — presentation logic exposed through Payload's admin UI. It defines what fields an editor configures and what data shape the frontend receives. Hero, FAQ, Cards, and CTA are blocks.

Component — an implementation detail inside the frontend codebase. Button, Container, Heading, and Modal are components that a block's React implementation might use internally, without ever being exposed to an editor directly.

Template — a code-defined composition of blocks for a structured content type. RecipeTemplate is a template; it decides the fixed order recipe blocks appear in.

Keeping these separate is what keeps the block library from sprawling: components support blocks, blocks provide the presentation editors can configure, templates compose blocks for fixed content types, and routes decide which of those paths a given request takes.

Common mistakes worth avoiding

A collection per visual variation. Landing Pages, Campaign Pages, and Standard Pages collections often end up storing near-identical block structures. Check whether these are genuinely different content types before splitting them apart.

A Payload block for every component. Buttons, containers, and layout wrappers don't need to be editor-configurable. Expose the presentation choices that matter and keep the rest as implementation.

Tenant checks scattered through routes. Resolve the tenant once, in resolveSiteFromRequest, and pass the result through a consistent site object rather than checking hostname conditionally across the codebase.

Structured content that becomes too freeform. A recipe should keep behaving like a recipe. Blocks are meant to add configurable flexibility within a content type's model, not replace that model entirely.

FAQ

Does every page on a Payload site need to go through the same route? No. The shared [[...slug]] route is for free-form editorial content. Structured content types — products, recipes, events — get their own collections and routes with fixed templates.

How does the frontend know which component to render for a given block? Each block entry in a page's layout array carries a blockType value matching the block's slug in its Payload config. The renderer looks up that value in a blockType-to-component map and renders the match.

Can different tenants use different versions of the same block? Yes. The Payload block definition and its data contract stay shared, while the block's React implementation can branch internally by tenant slug to render a different presentation.

What happens if an editor adds a block type the frontend hasn't implemented yet? The renderer's lookup returns nothing for an unregistered blockType, logs a warning, and skips that block rather than crashing the page. Registering the new block in blockRenderers is what makes it render.

Does this replace the need for SEO metadata handling per page? No — metadata generation still needs its own logic per route (or per document, for the shared route), typically pulled from SEO fields stored on the Payload document alongside the layout array.

Wrapping up

The shift this pattern asks for is where presentation logic lives. Payload's layout blocks array on a page document carries the editor's chosen structure; a block renderer maps each entry to a React component; a single catch-all route resolves tenant, locale, and path into that document. Structured content types keep their own collections and fixed templates alongside this shared route, rather than being forced through it. Once that split is in place, adding a new editorial page becomes a content operation instead of a pull request, and a new tenant reuses the same routing and rendering code with its own theme and content on top.

Let me know in the comments if you have questions, and subscribe for more practical development guides.

Thanks, Matija

I've walked several mid-market B2B clients through exactly this gap: companies with a CMS, a CRM, Search Console, an email platform, project archives, and a handful of AI subscriptions, still watching one useful article crawl through the organization for weeks before publishing. The software was never the missing piece. The missing piece was a defined system connecting the people, the data, and the decisions, and that's what I want to walk through here.

The Software Was Never the Bottleneck

A CMS gives your team somewhere to store and publish content. A content operating system defines how useful ideas get identified, how internal expertise gets captured, how material gets reviewed, how it gets structured, how it gets distributed, and how performance feeds back into the next decision. Those are two different layers, and confusing them is why so many CMS migrations disappoint six months later.

An established B2B company can have decades of experience, a strong reputation, and employees who understand the market at real depth, and still watch most of that knowledge stay trapped in conversations, project folders, email threads, and individual heads instead of reaching the website. A handful of ideas make it through to become content. The rest simply never gets captured, and no CMS upgrade changes that on its own.

A Better CMS Improves the Editor, Not the Workflow

Replacing an old CMS genuinely improves the editing experience: easier page building, reusable components, multi-language support, better permissions, less developer dependency. Those are real wins, and none of them answer the operational questions that determine whether the company actually publishes useful content on a consistent basis.

Questions like who decides what gets published, which data informs that decision, who provides the technical substance, who owns the first draft, who verifies factual claims, which approvals are actually required, where supporting images and files live, which fields are mandatory before something goes live, how content gets adapted for social and email, who checks whether it performed, how a successful topic gets expanded, how a weak page gets improved, and what happens to institutional knowledge when the expert who provided it leaves the company. A CMS can support each of these steps technically. Designing the actual process is separate work, and it's the work most companies skip.

The Pattern I See Constantly in Mid-Market Companies

This shows up repeatedly in established technical, industrial, manufacturing, distribution, and specialist service companies: too large to run content informally, not large enough to staff a dedicated team for every stage of production. Marketing is a small internal team, sometimes supported by agencies or freelancers. Technical staff hold valuable knowledge and limited time. Sales hears customer questions directly and rarely documents them systematically. Leadership wants more visibility, more leads, and better use of AI, while staying protective of accuracy and brand voice.

The result is a company with enough tools to run a sophisticated system and a workflow that stays improvised in practice. A typical article moves through something like this: marketing proposes a topic, a subject-matter expert gets asked for input, the expert sends a few notes two weeks later, marketing drafts from those notes, the draft circulates by email with comments scattered across three different threads, nobody's quite sure who has final approval, the approved copy gets manually pasted into the CMS, images get requested from another department, a LinkedIn version gets written separately, the newsletter team copies part of the article into another platform, campaign tracking gets added inconsistently, and the article publishes with nobody reviewing it again unless something's obviously broken.

That produces content. It doesn't build a repeatable operating capability, and those are different outcomes worth telling apart.

Content Operations Start Before the First Draft

Most content discussions start with the article itself, which is already too late. A stronger system starts with opportunity identification: a repeatable method for deciding which problems deserve content and which format fits, drawing on Search Console data, website analytics, paid search data, sales questions, CRM notes, support requests, product launches, project experience, competitor activity, regulatory changes, internal strategic priorities, and gaps flagged by subject-matter experts.

The goal isn't letting data dictate every decision. It's keeping the content calendar from being run entirely by opinion, habit, or whoever leadership talked to last. For each proposed piece, the company should be able to state the customer problem it addresses, the evidence that the topic matters, the intended audience, where it sits in the buying process, what the company knows that competitors likely don't, which business objective it supports, what the reader should do next, and how success will be measured. That connects content directly to commercial value instead of leaving the connection implicit.

The Seven Components of a Content Operating System

1. Demand intelligence

Demand intelligence identifies what the market is asking, comparing, evaluating, or trying to solve, pulling from search data, CRM information, sales observations, customer interviews, support questions, and market trends. The output should be a prioritized list of opportunities tied to existing pages, services, products, industries, or customer journeys, not a keyword spreadsheet nobody opens again.

A useful output might surface that a service page has high impressions and few clicks, that prospects keep confusing two product categories, that a technical question comes up in nearly every sales call, that several regional projects could support a location page, that buyers want a rough estimate before contacting sales, or that a page sitting near page one could climb with a focused round of additions. Demand intelligence answers where the company should invest attention next.

2. Knowledge capture

Once an opportunity is chosen, the company needs an efficient way to pull the relevant internal expertise out of the people who hold it, without handing an engineer, salesperson, or executive a blank page and asking them to write. A structured input works better: a recorded interview, a short workshop, a questionnaire, notes from a sales call, a project review, existing proposals, technical documentation, customer objections, photographs and diagrams, relevant data, and pre-approved claims and qualifications.

Expert participation should stay focused and time-limited. A 45-minute interview with the right person is often worth more than several weeks of delayed comments on a generic draft. The expert supplies judgment, context, examples, and corrections. The content team turns that into a usable structure.

3. Editorial production

Editorial production turns the source material into the right format: a service page improvement, a technical article, a comparison guide, a case study, an FAQ, a buyer's checklist, a regional landing page, an industry page, a calculator, a downloadable resource, a short social post, or a newsletter piece. The format decision should follow the customer's actual need. Some questions resolve better through a calculator, estimator, or guided form than through another 2,000-word article, and a deliberate system makes that call each time instead of defaulting to a blog post by habit.

4. Expert validation and governance

Factual review isn't optional for expertise-rich B2B companies, since the content in question often touches technical performance, compliance, safety, manufacturing, implementation, or operational risk. A polished piece carrying a misleading generalization damages trust fast. The governance layer should name who verifies technical accuracy, who approves commercial claims, who checks legal or regulatory exposure, who owns brand and editorial quality, who holds final publishing authority, and which changes trigger reapproval.

The level of review should scale with the risk: a company announcement needs a light marketing sign-off, a technical guide needs an engineer or product specialist's review, and a regulated claim needs legal or compliance approval. Distinguishing these cases up front keeps the company from publishing too loosely on one end or building an approval chain so heavy that nothing ships on the other.

5. Structured CMS publishing

The CMS should hold more than a single rich-text field. Depending on content type, useful fields include title, summary, body, author, expert reviewer, publication date, review date, content owner, category, industry, product or service relationship, geographic relevance, featured image, social image, SEO title and description, FAQs, related projects, related articles, calls to action, campaign parameters, approval status, translation status, and revision history.

That structure is what makes content reusable: a project entered once can surface on a service page, an industry page, a regional page, and a related-content block; an FAQ stored centrally can appear on every page it's relevant to; an article can feed a resource library, related-content recommendations, social distribution, and a newsletter, all from a single structured source. The CMS earns its value by representing the relationships inside the company's knowledge, not just the layout of individual pages.

6. Distribution workflows

Publishing on the website is the start of distribution, not the end of it. Approved content can adapt across LinkedIn, Facebook, email newsletters, sales enablement, internal knowledge systems, partner communications, customer onboarding, and industry portals, with the website staying the canonical source. Social and email should extend that source rather than becoming disconnected homes for the company's best material with no ownership behind them.

A practical distribution workflow detects that an approved article has published, reads its title, summary, image, URL, category, and campaign fields, prepares channel-specific drafts, routes them for review, publishes the approved versions, applies consistent tracking parameters, records status, and flags the content owner if a channel fails. This is where automation earns its place, since nobody should be manually re-copying the same title, link, excerpt, and image into four different systems, as long as editorial control stays intact where it matters.

7. Measurement and iteration

Publishing isn't the finish line. The company should come back to each piece and check whether visibility increased, rankings improved, clicks went up, the page attracted the intended audience, prospects engaged with related content, the article shaped sales conversations, it generated qualified inquiries, sales started reusing it, it resolved a question that used to eat staff time, and whether it showed up in an AI-generated answer.

That feedback loop is what turns publishing into an iterative system instead of a string of one-off campaigns.

Keep the Website as the Single Source of Truth

Many B2B companies end up running several disconnected content systems without meaning to: the website team publishes one version, the social team writes another, the email team drafts a third, and sales keeps a fourth in a slide deck. Claims drift apart, images differ, links go stale, and nobody's certain which version is the approved one anymore.

A stronger model keeps the complete, approved content inside the company-controlled system and lets every other channel receive an adapted version drawn from that source. A single technical article can become a short LinkedIn observation, a visual carousel, a newsletter summary, a sales follow-up link, three separate FAQs, and a section in a broader industry guide, all while staying connected back to one authoritative version that's easy to update.

Where AI Fits Inside the System

AI meaningfully speeds up query analysis, topic clustering, transcript summarization, draft outlines, first drafts, metadata, excerpts, social adaptations, internal-link suggestions, content classification, duplicate detection, translation support, content gap analysis, and review checklists. It performs best when processing and organizing material that's already grounded in real company data and expert input, and performs noticeably worse when asked to generate authoritative-sounding content without reliable source material behind it.

For an established B2B company, the workflow that actually holds up gives AI access to approved information, relevant source material, editorial rules, existing content, and structured data, then lets it prepare the useful work, while people make the calls involving truth, judgment, risk, and positioning. That's controlled acceleration, and it's a meaningfully different target than fully autonomous publishing.

Why Automating Too Early Backfires

Once a company sees the potential here, the instinct to automate everything at once is understandable. Collect the data, identify topics, generate content, publish it, distribute it, measure it, all running on its own. Automation layered onto a process the team doesn't fully understand yet tends to produce repetitive content, inaccurate claims, weak topic selection, duplicate pages, unclear ownership, excessive review overhead, inconsistent classification, context-free social posts, and a growing pile of material nobody actually trusts.

Running the workflow manually first surfaces which decisions are genuinely stable and which ones need ongoing judgment. A workable progression:

Stage 1: Manual execution. The team runs every step deliberately and documents what actually happens.

Stage 2: Standardization. Templates, checklists, roles, required fields, and approval rules get defined.

Stage 3: Assisted execution. AI and automation support research, drafting, classification, and distribution while people stay closely involved.

Stage 4: Selective automation. Stable, low-risk steps run automatically with human review at defined checkpoints.

Stage 5: Continuous optimization. Performance data drives prioritization and the system keeps getting more efficient.

This feels slower at the start. It's consistently faster than untangling a badly automated system after the fact.

Manual Overrides Belong in the System

Trying to remove every manual decision from a content system is rarely the right target for B2B publishing. Automatic related-content recommendations can run correctly most of the time and still need an editor's override on occasion. A social post can generate automatically while a specific campaign still needs custom messaging written by hand. A standard approval route can cover most articles while a regulated topic routes through additional review.

A good content operating system automates the predictable parts and keeps editorial judgment intact everywhere it's actually needed, so people spend their time on the decisions that genuinely require them.

Clear Ownership Matters More Than the Tech Stack

A company can build a technically excellent workflow and still watch it stall if ownership is vague. Each part of the system needs a named responsible person or role: marketing owns opportunity planning, sales contributes customer questions and commercial context, technical teams validate accuracy, leadership approves strategic positioning where required, compliance reviews regulated claims, a content owner manages publication, a platform owner maintains the CMS and automations, and marketing operations reviews performance.

In a mid-market company, one person often holds several of these roles at once, which is fine as long as each responsibility is explicit rather than assumed. Vague ownership is what stalls content between departments. Visible ownership is what makes the workflow measurable and improvable over time.

A Realistic First Version

A content operating system doesn't need to launch as a company-wide transformation. Pilot it around one commercially important service, product, industry, or problem, and define the demand input (which search queries, sales questions, and market signals get reviewed), the expert source (who holds the most useful practical knowledge), the output (page improvement, article, comparison, FAQ set, case study, or tool), the review step (who validates accuracy and approves publication), the CMS structure (which fields, categories, and relationships are required), the distribution plan (which channels receive adapted versions), and the measurement plan (which outcomes get reviewed after publishing).

Run that loop several times, document the delays, confusion, and repeated manual work that show up, and refine the workflow before investing heavily in automating any of it.

An Example Operating Flow

A practical version of this in motion: search and sales data surface a recurring customer question, marketing writes a content brief, a subject-matter expert sits for a recorded interview, AI converts the transcript and existing documents into an outline, marketing produces the first draft, the expert reviews the technical sections, the content owner finalizes the page, required CMS fields and relationships get completed, the approved article publishes, automation prepares LinkedIn and newsletter versions, marketing reviews and releases those adaptations, analytics and search performance get monitored, the team decides whether to update the page or build supporting material, and the underlying knowledge gets retained for future content and internal use.

Every step in that sequence has an input, an owner, an output, and a decision attached to it, which is what actually makes it an operating system rather than a workflow diagram.

The Value Reaches Past Marketing

A well-designed content operating system pays off outside the marketing function too. Sales gains reliable resources to send prospects before or after a call. Onboarding gives new employees structured explanations and real project evidence to learn from. Customer support gets consistent answers to recurring questions. Recruitment candidates get a clearer picture of the company's actual work. Approved company knowledge becomes usable inside internal assistants, search tools, and automated workflows. Institutional knowledge stays accessible after an experienced employee retires or leaves. And the company's visible digital presence starts to actually reflect its real level of experience, which matters most for companies whose current site understates what they know.

When a CMS Project Turns Into an Operating-Model Project

Companies often start this conversation asking for a better editor, more flexible pages, reusable components, improved SEO fields, easier publishing, social integration, and AI features. Those are legitimate requirements on their own. Partway through implementation, the deeper questions surface anyway: who owns the content, how should categories work, which content should be reusable, when should related content appear automatically, what requires approval, which system is the source of truth, where should AI be used, how should content move into social or email, and what should get measured.

At that point the project has moved past the website. It's really about how the company turns internal knowledge into market-facing assets, with the technology supporting that model rather than accidentally defining it.

What This Actually Comes Down To

A CMS stores an article. A content operating system explains why the article exists, where its information came from, who approved it, how it connects to everything else the company has published, where it gets distributed, and how the company decides what comes next.

Most established mid-market B2B companies already have the expertise, the data, and the tools this system needs. What's usually missing is the connective layer between them. Once that layer exists, the company stops depending on occasional bursts of publishing energy and gains a repeatable way to find useful opportunities, capture what its people know, produce credible material, distribute it efficiently, and learn from what happens next.

FAQ

Do we need new software to build a content operating system? Usually not right away. Most of the seven components run on tools you already have. The missing piece is almost always the defined process connecting them, not another platform.

Where should a small marketing team start if this feels overwhelming? Pick one component that's causing the most visible pain, usually knowledge capture or governance, and fix that one piece around a single pilot topic before touching the rest.

How do we handle governance without slowing everything down? Scale review to risk. A blog observation needs a light check. A technical or regulated claim needs a real expert or compliance review. Treating every piece the same is what creates the slowdown.

What happens to this system when a key subject-matter expert leaves? That's exactly the failure mode a structured knowledge-capture step protects against. Recorded interviews, structured notes, and a documented CMS reduce how much walks out the door with any one person.

Is this workflow only relevant for large enterprises? No. It's designed for mid-market companies specifically, since they have enough complexity to need structure and rarely have the headcount to run content by adding more people to the problem.

Let me know in the comments if you have questions, and subscribe for more practical guides on building content systems that hold up under scrutiny.

Thanks, Matija

I built this workflow running SEO audits and content clustering for established B2B clients, where the challenge was never a shortage of topics. Sales had a list of recurring questions, product teams wanted to explain technical differences, leadership had strategic themes to push, and marketing had a spreadsheet of keywords and half-finished drafts. What was missing was a defensible way to decide what to write first. That's what this workflow solves.

The Real Problem Is Prioritization, Not Ideas

Ask a sales or technical team at a decades-old B2B company to list content topics, and you'll get a year's worth of ideas inside one workshop. They know the recurring customer questions, the technical constraints, the purchasing risks, and the misconceptions that trip up less experienced buyers.

Ideas at that volume need a filter, because they carry very different amounts of value. Some questions come up constantly in sales calls but attract almost no search volume. Some keywords pull large audiences that have nothing to do with your actual buyers. Some topics are commercially important but so competitive that a single new article won't move the needle without a lot of supporting content behind it. Meanwhile, some of the biggest opportunities are already sitting on your own website: a page pulling thousands of impressions, ranked near the bottom of page one, converting almost none of that visibility into clicks.

Without a structured filter, content planning turns into a negotiation. The most senior person in the room picks the topic, marketing chases whatever trend is current, a competitor publishes something and gets copied, or an agency hands over a keyword spreadsheet nobody knows how to turn into a schedule. The output is a calendar full of reasonable ideas with no real order behind it.

Replacing "what should we write about" with "where is demand already proven and where is our site failing to capture it" turns content planning into a commercial investigation with evidence behind every decision.

Start From What You Already Own

Your website is probably already appearing for hundreds or thousands of relevant queries, whether people click through or not. Google Search Console shows exactly that: for any page, how many times it appeared in results, how many clicks it got, the click-through rate, the average position, the specific queries tied to it, and how all of that has moved over time.

That's demand attached to assets you already control. Google has already connected parts of your site to specific subjects, so the real question becomes whether those pages satisfy the searcher well enough to earn stronger visibility and more clicks. For a mid-market B2B company, improving a page that already has impressions is a more predictable move than publishing something new and waiting to find out whether Google decides it deserves to rank.

Four Signals That Reveal Real Opportunities

No single number tells you where to focus. A genuine opportunity shows up through a combination of four signals working together.

Impressions

Impressions tell you how often a page or query showed up in search results, which signals that Google already sees a connection between the search and your content. A page can rack up thousands of impressions and still convert almost none of them into visits, and that gap is frequently where the real opportunity sits.

Take a technical product page pulling 12,000 impressions, 24 clicks, a 0.2 percent click-through rate, and an average position of 9.2. Google has already surfaced this page for the right searches. The content, presentation, or positioning is failing to close the loop. Common causes include weak titles, a description that misses the search intent, thin content, a poor match between query and page, tougher competitors, missing supporting material, or a position that's technically on page one but far enough down to get skipped. The first move here is checking whether the existing page can be fixed before deciding to write something new.

Average position

Position tells you how far a page sits from meaningful visibility. A page ranking around 8 through 11 is often a realistic near-term win: a modest improvement can move it several places and meaningfully increase traffic. A page sitting around position 48 is a different kind of project, usually requiring stronger content, more internal and external links, or a broader supporting cluster before it climbs. Both are worth pursuing, they just carry different expected timelines and effort.

Click-through rate

Click-through rate shows how often people pick your result once they've seen it. A low rate needs context before you act on it: the page might rank too low to attract clicks, the query might only loosely match your content, an AI-generated answer might be sitting above your result, or the search intent might not match what your page delivers.

When a page combines high impressions, a reasonable position, and a very low click-through rate, that combination is worth investigating directly. The fix is sometimes editorial and sometimes technical or presentational: a sharper title, a clearer description, a relevant image, a stronger answer near the top of the page, or wording that matches how people are actually searching.

Commercial relevance

Search volume doesn't know your business priorities. A high-volume keyword can produce very little commercial value, while a lower-volume one can signal a buyer close to a real decision. Sorting queries by intent makes this visible:

All four categories carry value, but the highest-volume query is rarely the best first investment. A lower-volume comparison or decision-stage topic frequently pulls in more qualified buyers than a broad informational one.

Go From Site-Level Queries to Page-Level Patterns

Reviewing your site's top queries as one giant list gives a useful overview and is too broad to plan content from directly. Established company sites carry a lot of branded traffic: people searching your company name, locations, staff, or existing products. That traffic matters for other reasons and doesn't represent new market discovery.

Non-branded searches are where the growth signal lives, because those are people who may not know your company yet. The practical steps: open the performance report, switch the view from queries to pages, pull out commercially relevant pages with meaningful impressions, filter out anything dominated by branded or navigational traffic, then open one page at a time and review only the queries tied to it.

That page-level view is where the useful patterns show up. A single service page might be tied to hundreds of query variations covering definitions, product names, misspellings, use cases, comparisons, location terms, price questions, industry-specific phrasing, and a fair amount of noise. That list can look chaotic at first glance, and that's exactly the point where AI earns its place in the workflow.

Let AI Process the Volume, Keep the Decisions Human

Reading through several hundred queries by hand is possible and a poor use of a senior marketer's or technical expert's time. Export the page-level queries and metrics to a spreadsheet, hand it to Claude, ChatGPT, or another model, and ask it to strip out irrelevant queries, group similar phrases, separate branded from non-branded terms, flag question-based searches, classify intent, surface recurring themes, highlight high-impression low-click pages, and suggest whether each theme belongs on the existing page or warrants its own asset.

The AI here is interpreting demand Google has already recorded, not inventing it. A generic prompt like "give me blog ideas for an industrial company" produces plausible-sounding topics based on broad patterns. A prompt built from your own page-level queries, impressions, clicks, positions, and commercial context produces something grounded in your actual market presence, which is a meaningfully stronger starting point even though it still needs human review.

A workable prompt structure:

// File: prompts/content-opportunity-analysis.txt
Analyze the attached Search Console export for this service page. 
Remove irrelevant and branded queries. Group the remaining queries 
by search intent and recurring subject. Identify opportunities to 
improve the existing page, create FAQs, publish supporting articles, 
build comparison content, or create commercial landing pages. 
Prioritize opportunities using impressions, current position, 
click-through rate, and likely relevance to a mid-market B2B buyer. 
Do not recommend separate pages when they would substantially 
duplicate the existing page.

Layering in company context sharpens the output further: what you sell, your typical buyer, geographic coverage, average project value, key industries, sales cycle length, technical constraints, existing content, and any topics you deliberately want to avoid targeting.

Add Keyword Planner for the Market View Search Console Can't Give You

Search Console shows how your site currently interacts with demand. Google Ads Keyword Planner shows the market around that demand: average monthly searches, recent trends, year-over-year change, advertiser competition, approximate cost per click, and related terms and phrasing.

That data is useful even for companies with no plans to run paid campaigns, because competition and bid estimates give a rough read on commercial interest. Companies generally bid higher when a query connects to valuable business. A high cost-per-click can point to strong buyer intent, heavy competition, high customer value, a tough organic environment, or a broad term pulling in many different buyer types, so it's a signal to weigh alongside the rest, not a rule to follow on its own. A low-competition query can point to a genuine gap or simply weak commercial relevance, and the surrounding context usually tells you which.

Combined, these two sources answer sharper questions than either does alone: does this page already have momentum, is the topic growing or shrinking, are companies paying to reach this audience, are buyers using different wording than your site does, is the existing page targeting a phrase that's too broad, and is there enough demand to justify a dedicated comparison or guide.

Match the Format to the Intent

Not every opportunity needs a blog post. Picking the right format is one of the highest-leverage decisions in this workflow.

Improve the existing page when queries connect closely to a page's central subject. That can mean a clearer definition, better examples, stronger headings, technical specs, relevant images, cost factors, process explanations, embedded FAQs, internal links, or a case study. Creating a separate article to repeat what belongs on the service page itself just splits authority for no benefit.

Add FAQs for narrow, direct questions: installation time, cost drivers, upgrade paths, maintenance requirements, climate suitability, or what information an estimate requires. FAQs strengthen the existing page instead of forcing the reader to a second resource.

Write a comparison article when the data reveals genuine uncertainty between two alternatives. A strong comparison explains where each option performs best, the real trade-offs, cost and maintenance differences, and the conditions under which the recommendation changes, rather than declaring a universal winner.

Publish an educational guide when the topic needs more depth than a commercial page can reasonably hold: how a system works, how to plan a project, common mistakes, procurement considerations, or questions to ask suppliers. The guide should link naturally to the relevant service instead of functioning as a disguised sales page.

Build an industry page when one sector has distinct requirements, terminology, or project history worth showing directly: relevant services, specific challenges, applicable standards, project examples, and evidence of experience in that environment.

Build a location page when the company has real service coverage, local projects, and operational relevance to show, connecting services available in the area, local project evidence, and regional considerations. Producing near-duplicate pages with only the city name swapped creates volume without adding value.

Build a tool when the query itself signals that the user wants a decision rather than an article: cost estimates, sizing, compatibility checks, or eligibility. A calculator, estimator, or guided questionnaire can outperform a long-form article for both discoverability and lead qualification.

Validate With Sales and Technical Teams Before You Commit

Search data shows what people ask. It rarely shows why they're asking, whether the person asking is a serious buyer, or how the company should actually answer. That gap is where internal experience earns its place in the process.

Before committing real production time to a piece, check with sales or technical staff: do customers actually ask this, at what stage of the buying process, is the wording accurate, does it reflect a common misconception, is it commercially valuable, can the company answer it better than competitors, is there project evidence to draw on, are there claims to avoid, and what qualification would an inexperienced writer likely miss.

This step catches a specific failure mode: content that performs well in search while attracting the wrong audience. For a B2B company running lean on marketing capacity, one article that helps a serious buyer through a complex decision is worth more than a broad piece pulling in thousands of students, hobbyists, or unqualified visitors.

Score Opportunities Instead of Debating Them

A simple scoring model keeps this comparison consistent across topics. Rate each candidate from one to five on existing visibility, ranking opportunity, commercial intent, business relevance, expertise advantage, evidence availability, format fit, and conversion path.

The highest total shouldn't automatically set the publishing order, but it gives marketing, sales, product, and leadership a shared basis to debate priorities from instead of arguing from four different sets of assumptions.

Watch for Keyword Cannibalization

A large set of related queries can tempt a team into building a separate page for every variation, which usually backfires: multiple pages compete for the same intent, Google struggles to pick the most relevant one, internal link authority splits across pages instead of concentrating, and the company ends up with more maintenance and less depth per page.

Before adding a new page, check whether the query represents a genuinely different question with a substantially different answer, whether it targets a distinct industry, use case, geography, or buying stage the existing page doesn't cover, and whether the existing page could simply be expanded instead. A single strong commercial page, a handful of focused FAQs, one comparison article, and relevant case studies frequently outperform ten overlapping articles competing with each other.

Build Topic Clusters as Proof of Expertise

A single article rarely establishes strong authority on a competitive B2B subject, because search engines and AI systems weigh the broader body of connected content. A solid cluster typically includes a core service page, a detailed guide, a comparison article, several FAQs, a set of case studies, an industry page, a regional page, and a tool, all linked together.

Each piece plays a distinct role: the service page drives commercial action, the guide explains the subject, the comparison supports evaluation, the case studies prove real experience, the FAQ resolves narrow questions, and the tool helps the buyer self-qualify. The cluster works because the pieces cover the subject from connected angles instead of repeating the same text under different titles.

Run This as a Monthly Process, Not a One-Time Audit

A workable monthly cadence for a mid-market B2B team:

Week 1 — Identify the opportunity. Review pages with high impressions, low click-through rates, positions near page one, and strong commercial relevance. Pick one or two for deeper analysis.

Week 2 — Analyze demand. Export page-level queries, run them through AI for grouping and intent classification, and layer in Keyword Planner data and competitor observations.

Week 3 — Capture expertise. Interview the relevant salesperson, engineer, or project lead and collect examples, qualifications, and project evidence.

Week 4 — Publish and connect. Improve the existing page or publish the new asset, add internal links, FAQs, case studies, metadata, and imagery, and distribute through the right channels before tracking performance over the following months.

That cadence is sustainable for a company aiming for steady progress without building a publishing operation it can't maintain.

Measure What Actually Moves the Business

Rankings are a useful proxy and not the actual goal. A fuller measurement set includes growth in non-branded impressions, movement in average position, improved click-through rate, qualified organic visits, engagement with supporting pages, tool completions, contact requests, sales conversations shaped by the content, questions prospects stop needing sales to explain manually, content sales teams start reusing directly, visibility inside AI-generated answers, and revenue tied back to organic discovery.

Not every article produces a directly attributable lead. Some content lifts a service page's performance, some helps a prospect validate the company after a referral, some shortens the sales cycle, and some simply gives an AI system enough material to reference the company accurately. The underlying objective across all of it is making the company easier to discover and easier to trust.

Where Judgment Still Has to Come From People

Data shows where interest exists. AI processes the volume. Search tools estimate demand and competition. None of that carries knowledge of which customers you want more of, which projects are most profitable, which services are operationally constrained, or which topics drive the strongest sales conversations, so the final call stays with people who understand the business.

The workflow holds together because each piece corrects a weakness in the others: search evidence keeps the plan grounded in real demand instead of internal preference, commercial judgment keeps the plan pointed at relevant buyers instead of raw traffic, subject-matter experts protect accuracy, AI absorbs the repetitive analysis and drafting work, and ongoing measurement shows whether the whole thing produced value.

FAQ

How much Search Console data do I need before this workflow is useful? A few months of history is enough to start. Three to six months gives a more stable read on trends, but you can run the first pass with whatever data you currently have.

Should I always fix an existing page before writing something new? Check the existing page first when a query is closely related to a page you already have. If the existing page targets a different intent or a genuinely different audience, a new asset is the better move.

What if a topic scores well but sales says nobody actually asks about it? Trust the validation step. Search volume without a real corresponding buyer conversation is a weak signal on its own, and it's usually better spent on a topic sales can confirm firsthand.

How many queries does a typical service page carry in Search Console? Anywhere from a few dozen to several hundred, depending on the page's age and how broad its subject is. Older, broader pages tend to accumulate the most variation.

Can this workflow work without an SEO specialist on staff? Yes, as long as someone owns pulling the Search Console export monthly and someone technical is available to validate accuracy before publishing. The AI-assisted grouping step removes most of the specialist skill this used to require.

Publish the Next Most Valuable Thing

Most established B2B companies already have more content ideas than they can execute. The question worth asking isn't what to write next. It's where proven demand, existing visibility, commercial relevance, and a real expertise advantage all line up at once.

That question produces a different kind of content plan: one that favors targeted improvements over endless publishing, connects marketing work to real customer uncertainty, gives sales and technical teams a clear reason to contribute, and uses AI as an analytical assistant instead of an idea generator working from outside the business.

Let me know in the comments if you have questions, and subscribe for more practical guides on building content systems that hold up under scrutiny.

Thanks, Matija

I've run this process with manufacturers, signage companies, and specialist suppliers whose sales and technical teams could talk for an hour about installation constraints, regional requirements, and the mistakes newer competitors make, while their website said almost nothing beyond "quality, innovation, and excellent service." The gap between what a company knows and what a company publishes is the single biggest content opportunity I see in this segment, and it's fixable with a repeatable workflow rather than a content calendar.

The Gap Between What You Know and What You Publish

A company can operate successfully for 20, 30, or 50 years and still be unknown to the people evaluating it right now. A new prospect comparing suppliers has never sat in on a sales call. Google has never read your project files. An AI model summarizing your industry has never talked to your senior engineer.

These evaluators, human or algorithmic, work from what's actually published: your service pages, your articles, your FAQs, your case studies, your documented project history. They judge how clearly you explain hard problems and how well those explanations are backed by evidence. Everything that lives only in a salesperson's head or last Tuesday's client call is invisible to them, no matter how good it is.

The result is a company that feels highly differentiated internally and reads as generic externally.

Where the Knowledge Actually Lives

In an established B2B company, the useful knowledge is scattered across sales conversations, technical consultations, project folders, proposals, email threads, installation notes, internal training material, support tickets, and the personal experience of a handful of senior employees. Some of it sits in a CRM or shared drive. Most of it stays informal, in people's heads and in threads nobody archives properly.

Marketing usually knows this expertise exists and struggles to extract it. Subject-matter experts are busy, uninterested in writing articles, and often unsure which parts of what they know would actually help search visibility. Marketing can write clearly but frequently lacks the technical grounding to judge whether a claim holds up, whether a qualification is missing, or whether two solutions that look similar are actually interchangeable.

That mismatch produces a familiar cycle: marketing asks an expert to write something, the expert delays because client work is more urgent, marketing drafts from general online research, the expert reviews it late and flags it as too generic or technically off, and the piece gets shelved or published in a weakened form. After a few rounds of this, the company quietly decides that producing good technical content is too hard.

The actual fix is a knowledge-capture process the company hasn't built yet, and that's a structural problem with a structural solution.

Start With the Questions Your Company Already Answers

Skip the broad content calendar and start with questions instead. What do serious prospects ask before requesting a proposal? What does the sales team clarify on nearly every call? Which product differences get misunderstood most often? Where do geography, regulation, climate, scale, or installation conditions change the recommendation?

These questions already live inside the business, in calls, emails, demos, support tickets, and proposal conversations, and they also show up in your search data. Pulling the queries tied to an existing service page and comparing them against what sales and support hear on calls surfaces a small set of overlap questions: things people both search for and ask your team directly. That overlap is the highest-value content territory you have, because it's simultaneously in demand and commercially relevant.

Typical examples I see in this overlap: the difference between two product categories, expected lifespan, installation time, cost drivers, suitability for a given environment, maintenance requirements, compliance considerations, and what information a prospect needs to gather before requesting an estimate. Each of those is a signal of buyer uncertainty, and answering it well improves search visibility and sales readiness at the same time.

One Expert Conversation Should Produce More Than One Article

Treating every expert interview as fuel for a single blog post wastes most of the value in the conversation. A senior technical employee explaining how the company selects a solution for a given environment can support a full article, several standalone FAQs, a comparison page, a buyer's checklist, a service page section, a case study explanation, a sales enablement doc, a social post sequence, a newsletter, and internal AI knowledge for support or sales tooling.

The goal is to capture the underlying knowledge once, structure it properly, and reuse it across formats suited to different stages of the buying journey: an FAQ for a narrow question, a service page for the commercial offer, an article for context and education, a case study as proof, and a calculator or assessment tool to help the prospect self-qualify. Assembled together, these assets represent expertise far more convincingly than a stack of unconnected blog posts.

Why Real Authority Is Hard to Copy

AI-generated content has made high-volume publishing available to almost any competitor, including ones with far less practical experience than you have. That shift raises the value of first-hand detail: real project constraints, documented failure modes, judgment calls under specific operating conditions, and outcomes you can actually stand behind.

An article earns credibility when it explains when a recommendation changes, which variables matter most, what commonly goes wrong, what inexperienced buyers tend to miss, how your team weighs trade-offs, and what happened on a real project. Established companies already hold this material. The work is exposing it, not inventing it.

Your Project Archive Is a Knowledge Base, Not a Photo Gallery

Most companies treat project pages as portfolios: a photo, a client name, a short paragraph describing what was delivered. That confirms the work happened without explaining what it demonstrates.

A useful B2B case study captures what the customer needed, what made the project difficult, which constraints shaped the decision, which alternatives were considered, why the chosen approach fit, how delivery actually went, what the team learned, and which similar organizations face the same issue. That level of detail turns a project from a gallery entry into commercial evidence, and it lets you connect expertise to geography, industry, product type, and scale. Several projects from one region can anchor a regional service page; several from one sector can anchor an industry page; a recurring technical decision across projects can anchor a detailed guide.

Structure the Website Around How Prospects Actually Think

Organizing content purely by what you sell covers the basics and leaves value on the table. Prospects think in terms of problems, risks, decisions, industries, environments, and outcomes, and an experienced company already understands those dimensions well enough to structure content around them: by service, product, industry, application, customer type, geography, technical question, project type, or decision stage.

This isn't about building a page for every possible combination. It's about designing a content model where a product page links to relevant projects, an FAQ points to a detailed article, an industry page pulls together services and case studies for that sector, and a regional page shows credible local work instead of a city name inserted into generic copy. That kind of structure helps prospects navigate your expertise, and it helps search engines and AI systems understand how your content connects.

Where AI Fits, and Where It Doesn't

AI is genuinely useful for processing hundreds of search queries, grouping similar customer questions, turning meeting transcripts into structured notes, drafting outlines, producing first drafts from approved source material, adapting a finished article for other channels, generating metadata, and suggesting internal links. That's real time saved on repetitive work.

The judgment calls stay with people. An AI-generated explanation can sound convincing while quietly overlooking a constraint, generalizing advice that only applies in specific circumstances, or blending information from unrelated contexts. For expertise-heavy B2B companies, the model that holds up is human-in-the-loop: AI handles processing, organization, and first drafts; experienced people validate the substance; marketing shapes it for clarity and distribution; the company stays accountable for the final result. This is the same split I build into the SEO and content pipelines I run for clients, and it's what keeps AI-assisted production from drifting into generic-sounding output.

Don't Automate a Process You Haven't Defined Yet

It's tempting to ask whether the whole workflow can run on autopilot once the potential is clear. Search data collection, topic identification, draft generation, CMS publishing, and social distribution can all be automated at a technical level. Automating a weak process just makes it fail faster.

Run the workflow manually a few times first. Use those runs to figure out which data is genuinely useful, which questions are commercially relevant, which decisions need expert judgment, which formats actually produce value, how much review is necessary, who owns final approval, and what your quality bar looks like in practice. Once those answers stabilize, automate the repetitive steps around them. That order produces a system that fits how the company actually works, rather than a company forced to fit a system.

A Practical Starting Point

Pick one commercially important service or product and run this pilot before touching the rest of the site:

1. Review the existing page and its search performance.
2. Export the queries associated with it.
3. Ask sales and technical teams what prospects repeatedly ask.
4. Identify the gap between the website and what the company actually knows.
5. Run one structured expert interview.
6. Turn that interview into a core article or guide.
7. Extract several FAQs from the same material.
8. Connect the new content to existing services and project evidence.
9. Publish through the company's CMS.
10. Adapt versions for other channels.
11. Track whether visibility, engagement, and qualified inquiries move.
12. Document what worked before expanding to the next service.

This is the first working version of a repeatable knowledge-to-content pipeline, and everything after this pilot is scaling something you've already proven works once.

FAQ

How is this different from a normal content calendar? A content calendar starts from topics marketing thinks sound good. This process starts from questions your sales and technical teams already answer every week, then checks those questions against real search data before anything gets written.

Do subject-matter experts need to write the articles themselves? No. They need to talk through their reasoning in an interview. Turning that conversation into a structured article is a separate skill, and it's the part AI and a writer can handle once the substance is validated.

How much content can one expert interview realistically produce? A solid 45-60 minute interview on one recurring decision can support a full article, three to five FAQs, a comparison page, and a case study section. The limiting factor is usually structuring time, not raw material.

Where should a company with limited resources start? One page, one interview, one pilot run through all twelve steps above. Prove the workflow on a single service before building out a full content operation around it.

Does AI-generated content hurt or help in this model? It helps when it's confined to processing, drafting, and formatting, with an expert validating the substance before publishing. It hurts when it's left to generate claims unsupervised, because it can sound confident while missing a constraint that only someone with real project experience would catch.

The Real Opportunity

Established B2B companies are sitting on years of customer questions, project experience, and technical judgment that newer competitors can't fabricate. Most of that value currently lives outside anything a prospect, a search engine, or an AI model can see.

Turning that internal knowledge into a website that actually reflects it takes a system: internal knowledge capture, market demand data, expert review, content structure, publishing, distribution, and measurement, all connected. Once that system runs, the website stops being a brochure and becomes a real record of what the company has spent decades learning.

Let me know in the comments if you have questions, and subscribe for more practical guides on building content systems that hold up under scrutiny.

Thanks, Matija

I got here the ordinary way: iterating on an n8n workflow built around an AI Agent node, and hitting a wall that had nothing to do with my prompt engineering. The workflow would occasionally return a broken reply in production, and the only way to find out why was to open the n8n UI, click into the executions tab, and manually expand node outputs one at a time. That's fine for one bug. It stops being fine once you're iterating fast and the agent itself is misbehaving in ways that don't show up as an obvious crash. So I stopped treating n8n as a UI-only tool and started treating it as something Claude Code could read and write directly, the same way it reads and writes a repo.

This isn't a Claude Code vs. Codex piece — the pattern is identical for either. What matters is that your coding agent already knows how to run a CLI, read JSON, and reason about structured output. @n8n/cli gives it exactly that surface for a system that's normally locked behind a browser.

Authenticate with environment variables, not login

@n8n/cli ships an interactive login command that saves your instance URL and API key to a local config file. Skip it. Every subcommand also reads N8N_URL and N8N_API_KEY directly from the environment:

# File: (shell session, not a repo file)
export N8N_URL="https://your-n8n-instance.example.com"
export N8N_API_KEY="your-api-key"
npx @n8n/cli workflow list --format=json

Using env vars instead of login keeps the credential scoped to the current shell session rather than persisted to disk in a CLI config file your agent (or you, six months later) might forget is there. If your n8n API key is instance-wide rather than scoped to one project — common on a shared or self-hosted instance — this also means you're not leaving a standing credential file behind after the session ends.

Look at the whole instance before you touch anything

The first command I run in a fresh session is always the same, and it's not the one that touches the workflow I actually care about:

npx @n8n/cli workflow list --format=json

On a shared n8n instance, this single call tells you something a lot of people skip checking: how many other workflows exist, who they belong to, and whether your API key's reach extends beyond the one project you're supposed to be working on. I've worked on instances where one API key genuinely could see and edit every client's workflows. That's not a reason to avoid the CLI — it's a reason to run workflow list first, confirm the workflow ID you're about to touch, and keep every subsequent command scoped to that ID explicitly. An agent that only ever calls workflow get <id> and workflow update <id> for one confirmed ID is safer than one that goes hunting.

Pull the workflow as JSON and back it up first

npx @n8n/cli workflow get <workflow-id> --format=json > backups/workflow-id.$(date +%Y%m%d-%H%M%S).json

This is the step people skip because it feels like ceremony. It isn't. A live n8n workflow isn't a file in your repo with git history behind it — it's a row in n8n's own database, and n8n's built-in version history is not something I'd rely on as the only safety net when an agent is scripting structural changes to it. A plain JSON snapshot, timestamped, sitting next to your other project files, costs one command and gives you an actual rollback path if an edit goes wrong. Do this before every structural change, not just the first one.

Script the edit — don't hand-edit the JSON

Once you have the workflow JSON, the temptation is to open it and start editing fields by hand. Don't. A single n8n workflow can easily have ten or more nodes, each with its own parameters, credentials, typeVersion, and a connections graph that has to reference node names exactly. Hand-editing that JSON is how you end up with a dangling connection to a node you just renamed.

Instead, have your agent write a short Python script that loads the JSON, makes the specific structural change, and writes a new file:

# File: scripts/edit-workflow.py
import json

with open("backups/workflow-id.latest.json") as f:
    workflow = json.load(f)

for node in workflow["nodes"]:
    if node["name"] == "AI Agent":
        node["parameters"]["options"]["systemMessage"] += (
            "\n\nNever call the same tool twice with identical parameters "
            "— the result will be identical. Vary at least one real parameter."
        )

with open("edited-workflow.json", "w", encoding="utf-8") as f:
    json.dump(workflow, f, ensure_ascii=False, indent=2)

Before pushing anything, validate the graph structurally — every node referenced in connections should actually exist in nodes:

# File: scripts/validate-workflow.py
import json

with open("edited-workflow.json") as f:
    workflow = json.load(f)

names = {n["name"] for n in workflow["nodes"]}
errors = []
for source, by_type in workflow["connections"].items():
    if source not in names:
        errors.append(f"unknown source: {source}")
    for connections in by_type.values():
        for group in connections:
            for target in group:
                if target["node"] not in names:
                    errors.append(f"unknown target: {target['node']}")

print("errors:", errors or "none")

This one check catches the most common mistake an agent (or a human) makes when editing a node graph by script: renaming or removing a node and forgetting one of the connections that pointed at it. It costs nothing to run and it runs before the workflow ever reaches n8n.

Push safely: deactivate, update, reactivate — as three separate calls

npx @n8n/cli workflow deactivate <workflow-id>
npx @n8n/cli workflow update <workflow-id> --file=edited-workflow.json --format=json
npx @n8n/cli workflow activate <workflow-id>

If the workflow you're editing is active, structural changes — adding or removing nodes, rewiring connections — are safer applied while it's briefly deactivated, then reactivated once the update succeeds. Doing this as three separate CLI calls, rather than assuming workflow update alone is sufficient, gives you a clear point to stop and inspect the result before flipping the workflow back on. After the update, fetch it fresh with workflow get and confirm the node count and connections match what you expected — don't trust the update command's own echoed response as the only confirmation.

The actual payoff: debugging with live execution data

Everything above is table stakes. This is the part that changes how you work once you've done it a few times.

n8n keeps a full execution history, and @n8n/cli can pull it with node-level detail:

npx @n8n/cli execution list --workflow=<workflow-id> --status=error --format=json --limit=5
npx @n8n/cli execution get <execution-id> --includeData --format=json

The second command returns the complete runData for every node in that execution — every tool call, every input, every output, in order. This is the same information you'd normally have to click through node by node in the n8n UI, except now your agent can grep it, diff it across runs, and reason about it the way it reasons about a stack trace. Three real bugs came out of exactly this workflow in one session:

An AI Agent hit its iteration ceiling by calling the same tool sixteen times with identical arguments. Pulling the execution data showed every one of those sixteen calls had the exact same parameters — the model wasn't exploring different scenarios, it was just repeating itself until it ran out of budget. The fix was a one-line addition to the system prompt: never call the same tool twice with identical parameters, since the result will be identical every time. Obvious once you see the actual tool-call sequence; invisible from the outside.

A tool-call parameter format mismatch that sometimes self-corrected and sometimes didn't. A custom tool expected a parameter as a JSON-encoded string; the model occasionally sent it as a plain object instead, got a validation error back, and usually retried correctly — except when it didn't, at which point it burned through its remaining iterations on the same mistake. execution get --includeData surfaced the exact validation error text on the first bad call, which is the only way to know this is happening at all, since a self-correcting model looks completely fine most of the time.

The worst one: a silent empty response marked as success. When the agent exhausted its iteration budget after the above, n8n didn't return an error — the execution's own status field said "success" while the actual output was an empty string. That's a strictly worse failure mode than a crash, because nothing downstream knows to treat it as a problem; a user just gets a blank reply. The fix was a small Code node placed right after the AI Agent node, checking whether the output is empty and substituting a graceful fallback message before anything gets returned:

// File: (n8n Code node, placed after the AI Agent node)
const output = ($json.output ?? '').toString().trim();
if (!output) {
  return [{ json: { output: 'Something went wrong on my end — please try again in a moment.' } }];
}
return [{ json: { output } }];

None of these three bugs were visible from the chat interface sitting in front of the workflow. All three were visible in the first execution's full runData once I actually pulled it.

A shared-memory gotcha worth knowing about

One more failure mode, because it's easy to reproduce without realizing it: if you build a small classifier sub-agent (say, one whose only job is to extract a structured value from the latest message) and wire it to the same conversation-memory node as your main persona agent, the classifier can start "seeing" the full chat history — including the main agent's own prior replies — and drift into responding conversationally instead of returning strict structured output. It's not a prompt problem so much as a wiring problem: a classifier that only needs the current message doesn't need conversational memory attached at all. Removing that connection fixed it outright. If you have a sub-agent whose job is narrow and mechanical, keep its inputs narrow and mechanical too.

Prefer a deterministic node over an LLM judgment call

The last change worth calling out isn't a bug fix, it's a design correction. The workflow originally used an LLM call to answer a yes/no question — "is this value over a fixed threshold?" — before branching. That's outsourcing a comparison a plain IF node can do exactly right, every time, for free, with no latency.

The fix: have the LLM do the part only an LLM can do — pull a normalized number out of a sentence like "my budget is around forty-five thousand" — and hand that number to a plain n8n IF node for the actual comparison. Same outcome, less surface area for the model to get wrong, and a branch condition you can read and reason about without wondering what the model was thinking.

FAQ

Do I need n8n's paid/enterprise tier to use @n8n/cli? No — the CLI talks to any n8n instance's REST API using an API key, which is available on self-hosted and cloud instances alike. What matters is that the API key has access to the workflows you want to manage.

Is it safe to let an agent edit a workflow that's actively handling production traffic? Treat it the way you'd treat a production database migration: back up first, deactivate before structural changes, reactivate only after you've verified the pushed version with a fresh workflow get. Non-structural changes (like a system-prompt tweak) are lower risk, but the deactivate-update-reactivate sequence costs almost nothing and removes an entire category of "half-applied edit while live" failure.

Why not just use n8n's REST API directly instead of the CLI wrapper? You can — @n8n/cli is a thin wrapper around the same REST API. The CLI is worth using because it gives your agent a stable, documented command surface (workflow get, execution list, and so on) instead of hand-rolling HTTP requests and reading n8n's OpenAPI spec from scratch every session.

What if the agent introduces a bug during editing — how do I roll back? This is exactly why you back up the JSON before editing. workflow update <id> --file=<backup>.json restores the previous state as directly as the original edit was applied. Keep every backup file, not just the most recent one, since you may need to go back more than one step.

Does this replace testing the workflow manually? No. Execution data tells you what happened in a run that already occurred — it doesn't replace deliberately sending test messages through the workflow and checking the result. Use both: script the edits, then exercise the workflow with real inputs before you trust it.

Where this leaves you

The n8n UI is still where I'd go to eyeball a workflow's shape or drag a new node in for the first time. But once a workflow exists and you're iterating on it — tuning a system prompt, fixing a branch condition, chasing down why an AI Agent occasionally does something strange — @n8n/cli plus an agent that can script JSON edits and read execution data is a faster, more reviewable loop than clicking through the canvas and the executions tab by hand. The debugging technique alone — pulling full runData for a failed execution instead of guessing from the chat transcript — is worth adopting even if you never script a single structural edit.

Let me know in the comments if you have questions, and subscribe for more practical development guides.

Thanks, Matija

I run into this constantly across client sites with CDNs, service workers, and aggressive edge caching, and it always starts the same way: a client reports a broken page, I open it fine in Firefox or an incognito window, and Chrome alone shows the stale version. Here's the exact sequence I use to confirm it's a caching issue and clear it.

Confirm the Cache With a Query Parameter

Add a temporary query parameter to the affected URL:

https://example.com/problem-page/?test=1

This changes the URL enough that Chrome treats it as a new request instead of serving a cached response. If the page suddenly renders correctly, stale or corrupted cache data is almost certainly the cause, and you can move straight to clearing it instead of digging through the page's code.

Clear Chrome's Cache for the Site

A handful of fixes work through most cases, roughly in order of how disruptive they are:

1. Open the page in Incognito mode.
2. Clear site data for the affected domain.
3. Use Chrome's Empty Cache and Hard Reload option.
4. Clear Chrome's DNS cache and socket pools.
5. Test on a different network or on mobile data.
6. Check whether a proxy, CDN, service worker, or redirect rule is caching a bad response.

To clear data for one site specifically, open Chrome settings, search for the domain under stored site data, and remove it. Chrome DevTools offers a faster path for this during active debugging: open the Application panel, go to Storage, and select Clear site data.

Check for Trailing-Slash and Route-Level Caching

If the issue only shows up on one route, test both versions of the URL, since Chrome and some CDNs can cache them separately:

/example-page
/example-page/

A cache-busting parameter works here too:

/example-page/?refresh=1

If that query parameter clears the problem, the next step is usually clearing the relevant browser cache or purging the cached page directly from your CDN or hosting platform, since the stale copy is often sitting at that layer rather than in Chrome alone.

Rule Out the Browser Before Debugging the Code

Before assuming the website itself is broken, compare the page across normal Chrome, Incognito mode, another browser, another device, another network, and the same URL with a cache-busting query parameter. Six quick checks like this can save hours of debugging code that was never the problem.

FAQ

Why does this happen in Chrome specifically and not other browsers?

Each browser keeps its own cache, service worker registrations, and DNS resolver cache. Chrome tends to cache aggressively and hold onto service workers longer than some other browsers, so a stale response can persist in Chrome well after a CDN or origin server has already updated.

Does Incognito mode guarantee a clean test?

Mostly, but not completely. Incognito skips your existing cache and cookies, but it can still hit a cached response sitting at a CDN or proxy layer, so a correct result in Incognito narrows the problem to Chrome's local cache rather than ruling out caching entirely.

What's the difference between "Empty Cache and Hard Reload" and clearing site data?

A hard reload clears the cache for that page load only. Clearing site data through Chrome settings or DevTools removes cookies, local storage, service workers, and cached responses for the entire domain, which matters when a service worker is the actual culprit.

How do I know if the problem is a CDN cache instead of a Chrome cache?

If the cache-busting query parameter fixes the page in Chrome but the original URL still fails after clearing Chrome's cache and testing in Incognito, the stale response is most likely sitting at the CDN or proxy layer and needs to be purged there directly.

Should I add cache-busting parameters permanently to avoid this?

No. That defeats the purpose of caching and can hurt performance across your whole site. Use the query parameter only as a diagnostic step, then fix the actual cache configuration, service worker logic, or CDN purge behaviour causing the staleness.

Conclusion

A page that only breaks in Chrome is rarely a code problem. Confirming it with a cache-busting query parameter, then working through Chrome's site data, DNS cache, and any CDN or service worker involved, resolves most of these cases without touching a single line of application code. Let me know in the comments if you've run into a caching issue this didn't catch, and subscribe for more practical debugging guides.

Thanks, Matija

Moving from small-agency clients to enterprise clients isn't straightforward. I've been working through this shift directly while running a multi-brand CMS and DAM engagement for CanPrev, where security documentation, SSO, subprocessor tracking, and account ownership all became real deliverables rather than side notes. Here's what changed, section by section.

The Product Is Only One Part of the Deliverable

With smaller clients, the result is judged mainly by what shows up on screen. Does the application work, can users submit the form, can administrators update the content.

An enterprise evaluates a much larger system around the product, and will often expect technical architecture documentation, security documentation, hosting and infrastructure diagrams, role and permission definitions, deployment procedures, backup and recovery procedures, testing reports, user manuals, API documentation, monitoring and alerting, administrator training, a post-launch support model, and a plan for handing the system to another provider.

The code may represent half of the technical work. The other half consists of proving that the code can be operated, audited, maintained, and transferred safely. Documentation belongs in the estimate from the start, as part of the product itself.

Security Must Be Demonstrable

A small business may accept "the application follows security best practices" as a full answer. An enterprise will usually ask what those practices are, who owns them, and how they can be verified.

A security discussion at that level covers HTTPS and TLS configuration, Web Application Firewall protection, DDoS protection, coverage against the OWASP Top 10, secure authentication, multifactor authentication, enterprise single sign-on, role-based access control, audit logs, API rate limiting, secret and credential management, dependency updates, vulnerability scanning, encryption at rest, backup protection, data-retention policies, penetration testing, and incident response procedures.

The Avtolibre RFP is a good example of how specific this gets. It requests HTTPS, OWASP protection, a WAF, network-level and application-level DDoS protection, audit logging, and penetration testing, and it requires the contractor to remediate all Critical and High findings as part of the original scope.

That last detail carries commercial weight. A provider can estimate the effort to build the system and still miss the cost of preparing for a penetration test, supporting the test, investigating reported findings, remediating them, running regression testing, and completing a second validation round. Security requirements create engineering work, documentation work, and financial risk, so they belong in the estimate before development starts, not after it finishes.

Enterprise SSO Is Not Just a Login Button

Smaller projects commonly run on email-and-password or social login. Enterprise environments usually require integration with the organisation's identity provider, such as Microsoft Entra ID, Google Workspace, Okta, or another SAML or OpenID Connect provider.

The client typically expects employees to sign in with their existing corporate accounts, automatic access removal when an employee leaves, permissions driven by group membership, multifactor authentication that stays under corporate control, central visibility into sign-in activity, and distinct access policies for employees, partners, and administrators.

The technical integration itself is usually straightforward. The real complexity sits in defining who is allowed to access what: can all employees sign in, or must they be assigned to the application first? Which corporate groups map to which application roles? Are external partners included in the same identity system, and can a partner administrator invite other users? Who removes access when a partnership ends? Is emergency local access needed if the identity provider goes down? Are privileged actions recorded?

Enterprise authentication sits at the intersection of technology, HR process, IT policy, and security governance. A provider's job here goes beyond promising "SSO." It means understanding the client's identity model and defining the complete access lifecycle around it.

Data Location and Subprocessors Matter

A freelancer typically picks services based on cost, performance, and developer experience. An enterprise will ask where the data is stored, where backups live, whether support staff outside the EU can access the data, which third-party services receive customer information, whether the AI provider retains prompts or uses customer data for model training, what analytics data gets collected, whether IP addresses count as personal data, which subprocessors are involved, what happens when data must be deleted, and how quickly all customer data can be exported.

In the initial OTP discussion, the client raised GDPR, EU data residency, customer data storage, traceability, and control over AI actions directly. Architecture decisions in this context can't be made purely on ease of implementation.

A cloud database, an email provider, an analytics platform, an error-tracking service, and an AI API can easily add up to five separate subprocessors, each with its own data region, retention policy, and contractual terms. A responsible provider maintains a basic service register tracking the service name, its purpose, the data it processes, its hosting region, its retention behaviour, the responsible account owner, its contractual or data-processing status, and a replacement or exit strategy. Smaller agencies rarely need this level of tracking, and enterprise clients increasingly expect it.

Ownership Must Be Defined Before Launch

Account ownership is one of the most overlooked enterprise issues: who owns the domain, DNS and Cloudflare, the cloud account, the source-code repository, the database, object storage, email delivery accounts, analytics properties, monitoring services, API credentials, signing certificates, mobile application accounts, and backup encryption keys.

A small agency will often create these services under its own account because it's faster to set up. That convenience can turn into a serious enterprise problem once the client discovers a critical production system running on a freelancer's personal email address, a credit card belonging to the agency, a private GitHub organisation, a domain account internal IT can't touch, credentials stored on one developer's laptop, or an infrastructure account that resists transfer.

A better model has the client own production accounts and grant the provider the access it needs. Where agency-owned accounts are unavoidable, the contract and documentation should spell out what the agency owns, what the client owns, how billing works, how access will transfer, how long that transfer takes, and whether migration costs are included. Enterprise clients care about this because they need to keep operating without becoming permanently locked to one supplier.

Business Continuity Includes Your Business

An enterprise also evaluates the provider itself. For a two-person studio, the client is quietly asking what happens if the lead developer becomes unavailable, whether anyone else understands the infrastructure, whether the source code is documented, whether credentials are centrally stored, whether another supplier could take over, whether there's a backup contact, whether releases depend on one person's laptop, and whether the provider has capacity for an urgent incident. This is usually called key-person risk.

A small provider doesn't need a hundred employees to answer these questions well. It needs to show that its size doesn't translate into operational fragility. Practical controls include shared repositories, password-manager access, documented deployment procedures, infrastructure as code, centralised environment-variable management, a clear backup contact, regular handover documentation, client access to production systems, automated testing and deployments, and a realistic support and escalation process. None of this eliminates the value of a specialist; it just keeps specialist knowledge out of a single person's head.

Support Expectations Must Be Specific

"Post-launch support" means different things to different people. A provider may read it as fixing occasional bugs when time allows. A client may read it as guaranteed response times, business-hours coverage, emergency coverage outside business hours, security patching, infrastructure monitoring, backup monitoring, incident investigation, dependency upgrades, browser compatibility updates, small content or configuration changes, monthly reporting, and a guaranteed amount of development capacity.

Turning these into explicit service levels closes that gap: a critical incident gets a response within one hour, a high-priority incident within four business hours, a normal defect within two business days, planned maintenance gets communicated several days ahead, security updates get assessed and applied by severity, and backups get monitored automatically with restoration tested periodically.

A small agency should think carefully before promising 24/7 support without the people and systems to back it up. A narrower, credible service level holds up better over time than an impressive SLA the team can't actually fulfil.

Change Management Becomes More Formal

In smaller projects, scope evolves through informal messages: could you also add this field, can we slightly change the workflow, this should probably connect to the CRM as well.

In an enterprise engagement, small changes can ripple into security, compliance, data models, integrations, training, testing, documentation, project timelines, and other suppliers. A formal change process doesn't need to be bureaucratic to handle this. It just needs to record what is changing, why, who requested it, what it affects, the estimated cost, the timeline impact, and who approved it.

Enterprise clients generally accept change requests once the consequences are explained clearly. The friction usually comes from the provider absorbing dozens of small changes quietly and only raising the issue once the project is already late.

Acceptance Is More Important Than "Finished"

A freelancer may treat a project as complete once the agreed features are built. An enterprise typically treats it as complete once user acceptance testing has passed, security findings are resolved, performance targets are met, documentation is delivered, administrators are trained, production access is approved, backups are verified, monitoring is operational, and the internal project owner has formally accepted the milestone.

Contracts should define acceptance criteria for each phase. Without that, a provider can believe a milestone is done while the client believes it's still open, which delays invoices and creates disagreement over whether outstanding requests are defects, missing requirements, or new scope.

Internal Stakeholders Are Part of the System

Enterprise buying decisions rarely come from one person. A project can involve a business owner, marketing, IT, security, legal, compliance, procurement, finance, data protection, customer support, external penetration testers, existing technology suppliers, and senior management, and each of them sees a different risk. Marketing weighs speed and flexibility, IT weighs maintainability, security weighs access control, procurement weighs contractual protection, and finance weighs payment terms and predictable cost.

A strong provider treats these stakeholders as a source of requirements rather than an obstacle. Their questions describe exactly what the organisation needs in order to approve and operate the system, and part of the provider's job is translating between them. That's why enterprise work tends to include more meetings, written decisions, and approval stages than the technical complexity alone would suggest.

Evidence Is More Valuable Than Reassurance

When an enterprise asks whether backups exist, "yes, the hosting provider handles that" is a weak answer on its own. A stronger answer names the backup frequency, retention period, storage location, encryption status, last successful backup, last restoration test, responsible person, and recovery procedure.

The same principle carries over to security, performance, and availability. Security claims land better backed by dependency scan results, security headers, access-control documentation, penetration-test reports, patch procedures, and audit logs. Performance claims land better backed by Lighthouse results, load-test results, API response measurements, and monitoring dashboards. Enterprise trust gets built on evidence like this, not on assurances alone.

The Commercial Model Must Account for Enterprise Overhead

A common mistake treats an enterprise project as a bigger version of a normal website, estimating design and development hours while missing procurement calls, security questionnaires, architecture reviews, stakeholder workshops, documentation, training, penetration-test remediation, deployment coordination, status reporting, acceptance support, legal and compliance discussions, delayed decisions, and extended payment terms. All of that work is real and belongs in the price.

Enterprise projects also carry contractual clauses around warranties, intellectual-property ownership, confidentiality, data processing, indemnification, service levels, liability, security incidents, subcontractors, termination assistance, mandatory remediation, and insurance requirements. A small provider should read unlimited liability, broad indemnification obligations, and commitments that exceed the total contract value especially carefully. A larger contract is genuinely attractive, and it's worth knowing exactly how much risk comes attached to it.

What a Small Agency Should Prepare

A small agency doesn't need a large corporate structure to approach enterprise clients. It needs a professional operating baseline, which at minimum looks like: a standard architecture document, a security and hosting overview, a list of subprocessors and services, a role and access-control model, a backup and recovery description, a deployment and rollback procedure, a support and escalation model, a standard Data Processing Agreement process, clear ownership of infrastructure and accounts, a handover and exit plan, a change-request process, milestone acceptance criteria, a secure credential-management process, evidence of testing and quality assurance, and a realistic explanation of team capacity and continuity.

None of this needs to run hundreds of pages. A concise, accurate document holds up better than an impressive policy copied from a large corporation and never actually followed.

The Main Shift in Mindset

Enterprise clients aren't asking for bureaucracy for its own sake. They're working through legitimate questions: can this system expose customer data, can it survive an outage, can employees access only what they should, can we prove what happened during an incident, can we replace the provider if necessary, can the system grow without a rebuild, can our legal and security teams approve it, can the provider support it after launch, can senior management trust the project.

A freelancer or small agency can serve enterprise clients well without turning into a traditional large consultancy. A specialist provider often moves faster, makes sharper technical decisions, and gives more senior attention than a larger agency would, and pairing that speed with discipline is what makes the engagement work.

Enterprise readiness isn't about headcount or slide decks. It's about delivering a system whose risks, ownership, operation, and future are fully understood. The client isn't only buying the application built today. They're buying confidence that it stays secure, operable, and supportable tomorrow.

FAQ

How is estimating an enterprise project different from estimating a normal website?

The build hours look similar at first glance. The difference comes from the surrounding work: documentation, security reviews, penetration-test remediation, stakeholder workshops, and acceptance support all need their own line items, or they quietly eat the margin.

Does a small agency need enterprise-grade tooling to take on these clients?

No. It needs a professional operating baseline: documented architecture, clear account ownership, a defined support model, and evidence of testing. These can be built incrementally and don't require a large team.

What's the single most common mistake small providers make with enterprise clients?

Treating account ownership and documentation as afterthoughts. Services created under a personal account or left undocumented become the hardest things to unwind once the client asks for a transfer plan.

Is enterprise SSO harder to implement than social login?

The integration itself is usually not the hard part. The hard part is defining the access lifecycle: who gets in, which groups map to which roles, and who removes access when someone leaves.

Should a small agency promise 24/7 support to win enterprise deals?

Only if it can actually deliver it. A narrower, honest service level performs better over the life of the contract than an SLA the team can't consistently meet.

Conclusion

Enterprise clients aren't buying a bigger version of the same website project. They're buying documented architecture, demonstrable security, defined account ownership, specific support levels, and evidence that the system keeps running without becoming dependent on one person or one supplier. A small agency that builds this operating baseline can serve enterprise clients well, often with more speed and senior attention than a larger consultancy provides. Let me know in the comments if you have questions, and subscribe for more practical guides on running a technical agency.

Thanks, Matija

I ran into this exact requirement while designing a multi-brand CMS and digital asset management platform. The client already managed every employee through Google Workspace, so this guide walks through how the identity check and the application's own access rules stay cleanly separated, and how to wire that separation into a Payload CMS user model.

The problem with separate application accounts

A new internal application often ships with its own users table, registration flow, password policy, reset process, and account-removal step. Employees end up remembering another password. Managers end up requesting accounts for new hires. Administrators end up disabling accounts by hand when people leave, and application owners end up fielding password-reset requests while maintaining their own authentication security. This workload multiplies once the application serves multiple brands, departments, agencies, and external partners.

Single sign-on moves the initial identity check to the company's existing identity provider:

Google supports authentication through OpenID Connect and Google Identity Services. Microsoft Entra ID implements OpenID Connect on top of OAuth 2.0. Both systems issue a signed identity response that an application can validate before creating a local session.

The basic SSO flow

The login process runs through six steps. The employee opens the company application and selects "Continue with Google" or "Continue with Microsoft." Google or Microsoft authenticates the employee and returns a signed identity response. The application looks up or creates the corresponding local user, then starts its own session and applies its own access rules.

The employee never creates a separate application password, and the application never receives the employee's Google or Microsoft password. The identity provider handles that exchange and hands back a limited set of verified identity claims: a stable provider identifier, email address, name, profile image, and Workspace domain or Microsoft tenant information.

The application should store the stable provider identifier rather than relying on email alone. Email addresses get renamed or reused, while the provider identifier stays fixed to the account.

Authentication and authorization remain separate

SSO handles authentication: confirming this is a verified employee from the approved company account. The application handles authorization on top of that: deciding this employee can edit Brand A content, review Brand B assets, and view reports.

A CMS or DAM might store a user record like this:

{
  email: 'employee@company.com',
  identityProvider: 'google',
  identityKey: 'google:provider-user-id',
  roles: ['editor'],
  brands: ['brand-a'],
  departments: ['marketing'],
  active: true
}

Google or Microsoft handles the employee's credentials, multifactor authentication, and company account status. The CMS or DAM handles admin access, editorial roles, asset permissions, brand access, approval rights, field-level restrictions, and audit relationships.

Payload CMS supports authentication-enabled collections, custom authentication strategies, collection access control, field access control, and Admin Panel restrictions based on the authenticated user.

Automatic user creation

Many business applications use just-in-time provisioning, where the first successful company login triggers creation of the local application user:

Google or Microsoft verifies employee
                ↓
Application searches for identity key
                ↓
No application user exists
                ↓
Application creates a user with safe defaults
                ↓
Administrator assigns additional access

The default role should stay restrictive, with a new employee starting as a viewer or inactive user until an administrator assigns the correct brands and permissions. This removes the registration step while keeping access controlled from day one.

Google Workspace and Microsoft Entra ID compared

Both platforms support modern SSO, and their enterprise administration models differ in the details:

Google Workspace administrators can trust, restrict, or block which internal and third-party OAuth applications employees may access, and limit the Google data scopes those applications request. Microsoft Entra registers an application against a single tenant, so a tenant-specific authority ensures only members and permitted guests from the selected organisation can authenticate.

SSO does not require access to company documents

A login integration does not automatically grant access to Gmail, Google Drive, Outlook, SharePoint, or Microsoft Graph. The application can request only basic identity scopes:

openid
email
profile

Additional services require additional OAuth scopes and explicit approval. This separation matters during security review, since an internal CMS can confirm who the employee is without reading any Workspace documents or mail. Google allows administrators to configure access according to the exact OAuth scopes an application requests.

Offboarding and account removal

SSO improves offboarding because the employee's central company account controls their ability to authenticate again. Disabling a Google Workspace or Microsoft Entra account prevents the employee from completing a new login.

The application still has to manage any session that already exists. A production design should include a limited session duration, an active flag on the local user, session revalidation, immediate application-level suspension, audit records, and optional directory synchronization.

Larger organisations can automate this further with SCIM, which creates, updates, and deactivates application users based on the company directory. Basic SSO confirms identity at login, and directory provisioning keeps the local application user synchronized for the rest of the employee lifecycle.

SSO for a CMS or DAM

SSO earns its keep on internal content and asset platforms serving marketing teams, product teams, legal reviewers, designers, external agencies, regional offices, and administrators. The organisation already knows who these people are through Workspace or Entra ID, so the DAM can reuse that identity and layer application-specific access on top.

A Google Workspace login could produce this mapping:

Verified Google Workspace employee
                 ↓
Payload user
                 ↓
Brand: CanPrev
Role: Editor
Department: Marketing

A Microsoft Entra environment could map an internal group to application access:

Entra group: Legal Reviewers
                 ↓
Payload role: Approver
Brand access: All brands

This keeps credentials centralized in one place while preserving granular application authorization.

Custom implementation or enterprise SSO product

Two implementation routes handle this well, depending on scale:

Payload sells an Enterprise SSO feature supporting SAML and OAuth 2.0 identity providers, including Google, Microsoft, and Okta, with automatic profile generation and permission mapping. The open-source version supports custom authentication strategies, so a development team can implement Google Workspace or Microsoft Entra authentication directly, taking on security, testing, upgrades, and long-term maintenance as part of the build.

When SSO creates the most value

SSO pays off once an application has more than a small number of internal users, regular employee onboarding and offboarding, multiple departments or brands, sensitive business information, company-wide multifactor authentication, external agencies or guests, formal security review, or granular roles and approvals. A public customer application may still need separate customer authentication, while an internal CMS, DAM, portal, knowledge system, or workflow application is usually a strong SSO candidate.

FAQ

Does SSO remove the application's users collection?

No. The application still needs local users for roles, permissions, relationships, preferences, and audit history. SSO replaces the separate application password.

Does the application receive the employee's Google or Microsoft password?

No. The employee authenticates directly with Google or Microsoft, and the application receives a signed identity response.

Can any personal Google or Microsoft account log in?

The application should restrict access to the approved Workspace domain or Microsoft Entra tenant. Company administrators can also restrict which applications employees are allowed to use.

Does SSO automatically remove a user when they leave?

It prevents future authentication once the company account is disabled. Existing application sessions and local user status still need explicit handling, which SCIM or directory synchronization can automate.

Is SSO only available to enterprise companies?

The protocols are open and broadly available. Enterprise products package provider support, configuration, maintenance, and vendor accountability on top of that. Smaller teams can build a focused OpenID Connect integration for their own applications.

Conclusion

Single sign-on creates a cleaner employee experience and a stronger access-control model for business applications. Google Workspace and Microsoft Entra ID already manage employee identities, and a CMS, DAM, internal portal, or workflow application can reuse that identity while keeping its own roles and permissions:

Google or Microsoft
Identity and company authentication

Payload CMS or business application
Roles, permissions, brands and access control

This split removes duplicated passwords, improves onboarding, centralizes authentication policy, and gives internal applications a more credible enterprise security model.

I design Next.js and Payload CMS platforms for organisations managing multiple brands, teams, workflows, and business systems. Let me know in the comments if you have questions, and subscribe for more practical development guides.

Thanks, Matija

I just finished wiring this up for a client's Next.js 16 marketplace app, and shipped it all the way through to a real production deployment behind Docker and a self-hosted CI pipeline. The SDK setup took twenty minutes. Getting it to actually fire in production took a lot longer, because of a failure mode that doesn't show up in local development, doesn't show up in a "successful" deploy log, and doesn't show up unless you specifically go check the network tab. This guide covers both halves: the integration itself, and the deployment trap that will silently disable it if you don't know to look for it.

Why posthog-js directly, not the snippet or @posthog/next

PostHog gives you three ways to get their SDK into a page, and they're not interchangeable once session replay and privacy are in scope.

The classic <script> snippet — the one PostHog's own onboarding hands you by default — loads the SDK from a CDN and self-assigns to window.posthog. It works, but it's a black box you can't type-check, and it initializes unconditionally the moment the script tag executes, which makes consent-gating clumsy: you either avoid injecting the tag until consent is granted (delaying the CDN fetch on every page load) or you load it and then try to bolt opt-out behavior on afterward.

@posthog/next wraps the SDK for Next.js specifically, but at the time of writing PostHog itself labels it pre-release. I don't put pre-release packages in front of a paying client's production traffic, and you probably shouldn't either.

posthog-js installed as a normal npm dependency gives you the same SDK, minus the CDN round trip, with full TypeScript types, and — critically for this guide — direct control over exactly when .init() runs. That control is what makes consent-gating and privacy masking actually reliable instead of best-effort.

pnpm add posthog-js

Client init in instrumentation-client.ts

Next.js has a dedicated convention for client-side instrumentation: a file named instrumentation-client.ts, sitting next to your app directory (not inside it), that runs once in the browser before your app hydrates. It's the right place for anything that needs to exist before React takes over — error tracking, and analytics init both belong here.

// File: src/instrumentation-client.ts
import posthog from 'posthog-js';

const projectToken = process.env.NEXT_PUBLIC_POSTHOG_PROJECT_TOKEN;
const apiHost = process.env.NEXT_PUBLIC_POSTHOG_HOST;
const analyticsEnabled = process.env.NEXT_PUBLIC_ANALYTICS_ENABLED === 'true';

if (analyticsEnabled && projectToken && apiHost) {
  posthog.init(projectToken, {
    api_host: apiHost,
    defaults: '2025-05-24',
    opt_out_capturing_by_default: true,
    capture_pageview: false,
    session_recording: {
      maskAllInputs: true,
      maskTextSelector: '.ph-mask, [data-private="true"]',
    },
  });
}

Three things in that config matter more than the rest. opt_out_capturing_by_default: true means the SDK loads but captures nothing until something explicitly opts it in — this is what makes consent-gating actually safe, versus loading the SDK and hoping you remembered to guard every capture call. The analyticsEnabled check means a missing or false NEXT_PUBLIC_ANALYTICS_ENABLED skips initialization entirely — local development and any environment that hasn't been given real PostHog credentials stays completely inert, with zero network calls to PostHog, which is exactly what you want on a laptop that isn't your production traffic. And capture_pageview: false is deliberate: App Router navigation doesn't match the classic multi-page-load model PostHog's autocapture assumes, so pageviews get fired explicitly later instead of relying on the default heuristic.

Wiring into your existing cookie consent

If your site already has a cookie consent banner — and if you've read the GDPR-compliant Vercel Analytics guide, you already know why it should — the mistake to avoid here is building PostHog a second, parallel consent store. It should hook into the one you already have.

// File: src/lib/analytics/consent.ts
import posthog from 'posthog-js';

export function applyAnalyticsConsent(granted: boolean): void {
  if (granted) {
    posthog.opt_in_capturing();
  } else {
    posthog.opt_out_capturing();
  }
}

Call applyAnalyticsConsent from the exact same accept/decline handlers your consent banner already calls for whatever else it gates — Google Tag Manager, a marketing pixel, whatever. Don't introduce a second cookie key or a second localStorage flag just for PostHog; one source of truth for consent means one place to audit when you need to prove GDPR compliance later, and one place to fix if the logic is ever wrong. On mount, also check whatever your existing consent storage already holds — if the user accepted on a previous visit, apply that immediately rather than waiting for them to click the banner again, since it won't show a second time.

Session replay privacy: masking inputs and sensitive text

Session replay is the single biggest reason to reach for PostHog over Vercel Analytics or GA4 — watching an actual recording of where someone hesitated in your checkout flow tells you things a funnel chart never will. It's also the single easiest way to accidentally record someone's password, email, or payment details if you don't configure masking before you ship it, not after.

maskAllInputs: true in the config above is the blanket default — every <input>, <textarea>, and <select> gets its value replaced with asterisks in the recording, full stop. That covers form fields. It doesn't cover rendered text: if your app ever prints a customer's email address or name back onto the page — a confirmation screen, an account settings page — that text is visible in the recording unless you mark it explicitly.

// File: src/components/account/ProfileSummary.tsx
<span className="ph-mask">{customer.email}</span>

For an entire section that should never appear in a recording at all — a payment form, an identity verification step, anything with real financial or personal data — go further than masking and exclude it from capture entirely:

// File: src/components/checkout/PaymentDetails.tsx
<section data-ph-capture-attribute-exclude="true" className="ph-no-capture">
  {/* payment fields never enter the recording, not even masked */}
</section>

Don't reach for .ph-mask on every element as a defensive habit, though — public prices, vehicle names, navigation labels, anything that isn't personal to the specific visitor should stay visible, or the recording becomes useless for the thing you built it for in the first place.

A typed trackEvent() wrapper

Once the SDK is initialized and consent is wired up, resist the urge to sprinkle posthog.capture('some_event', {...}) directly into every component that needs to fire something. Centralize it, and get compile-time safety on event names and their properties while you're at it.

// File: src/lib/analytics/events.ts
export type AnalyticsEventMap = {
  vehicle_viewed: { vehicle_id: string; partner_id?: string };
  search_submitted: { search_type: 'classic' | 'affordability'; result_count?: number };
  application_submitted: { reference: string; product?: string };
};

export function trackEvent<TEvent extends keyof AnalyticsEventMap>(
  event: TEvent,
  properties: AnalyticsEventMap[TEvent],
): void {
  if (typeof window === 'undefined') return;

  posthog.capture(event, properties);

  window.dataLayer = window.dataLayer ?? [];
  window.dataLayer.push({ event, ...properties });
}

The AnalyticsEventMap type means a typo in an event name or a missing required property fails at build time instead of silently vanishing in production — which matters more than it sounds like it should, because a dashboard built around an event that stopped firing three deploys ago is a very quiet kind of broken. The dataLayer.push is there for teams running Google Tag Manager alongside PostHog rather than instead of it; if you've already got GTM wired up per the Next.js GTM guide, this lets the same event reach both without duplicating the capture call at every site.

CSP additions

If your site runs a Content-Security-Policy — and it should — PostHog needs explicit allowances or its script, its session recording payloads, and its API calls will get silently blocked by the browser with nothing but a CSP violation buried in the console to explain why nothing's showing up.

script-src 'self' https://*.posthog.com;
connect-src 'self' https://*.posthog.com;
worker-src 'self' blob: data:;

The worker-src line is the one people forget: PostHog's session recorder runs part of its work in a web worker, and without blob: and data: allowed there, recording fails quietly rather than throwing anything you'd notice in normal testing.

The deployment gotcha: env vars that disappear at build time

Here's the part that actually cost time. Everything above worked flawlessly in local development the first time I ran it. It worked in a browser-based check against the compiled dev bundle. Then it shipped to production, the deploy pipeline reported success, the health check passed — and PostHog never received a single event.

The root cause has nothing to do with PostHog and everything to do with how Next.js handles NEXT_PUBLIC_* environment variables. They aren't read at runtime by the server process the way DATABASE_URL or a secret key would be. They're inlined as literal string values into the client JavaScript bundle at next build time. If a NEXT_PUBLIC_* variable isn't present in the environment when next build actually runs, Next.js compiles the reference to undefined — permanently, into that build's output — and no amount of setting the variable correctly in your runtime container afterward will change it. You'd have to rebuild.

That distinction is easy to miss if your deploy pipeline separates "build" from "run" into different steps with different environment sources — which is exactly what a Docker-based pipeline does by design. In my case, the build stage sourced its environment from a secret file assembled by a small shell script, and that script filtered which variables got forwarded into the Docker build through a hardcoded allowlist — a list that had never been updated to include the new PostHog variables. The runtime .env files on the server had the right values. The application code was correct. The deploy succeeded, the container passed its health check, and the client bundle it served had literally never seen the PostHog token at all.

# The gotcha, made concrete: what actually gets read
next build          # NEXT_PUBLIC_* vars get inlined into the client bundle HERE
docker run <image>  # setting NEXT_PUBLIC_* vars here does nothing — too late

If you're on a similar split-stage pipeline — anything where docker build and docker run (or their Kubernetes/Nixpacks/whatever equivalents) read from different environment sources — go check whatever mechanism forwards environment variables into your build step specifically, not just your runtime container definition. A hardcoded allowlist, a .env file that only gets copied at deploy time, a CI secret that's scoped to "deploy" but not "build" — all of these produce the identical symptom: correct code, correct runtime config, a deploy that reports success, and a feature that's permanently, silently off until someone rebuilds with the variable actually present at build time.

Verifying it end-to-end

The lesson from the section above is really about verification method, so make it explicit: a green checkmark on your deploy pipeline proves the container started. It does not prove a NEXT_PUBLIC_*-dependent feature actually works. The only real proof is checking what the browser actually sent.

Open your production site in a real browser, open dev tools, and before accepting the cookie consent banner, confirm the network tab shows zero requests to your PostHog host — that's opt_out_capturing_by_default doing its job. Accept consent, and confirm you now see a POST request to <your-host>/e/ (event capture) with a 200 response, and — if session recording is enabled — a POST to <your-host>/s/ as well. If your PostHog host is on the EU cluster, that's typically eu.i.posthog.com; use whatever host your project settings actually show you, not a guessed value. Finally, open PostHog's Live Events view and confirm the same events are landing there in real time, with no personal data sitting in the event properties.

That sequence — no requests before consent, real 200s after consent, events visible in PostHog's own dashboard — is the only check that actually proves the integration works. Everything before that step is necessary but not sufficient.

Frequently asked questions

Does PostHog work with Google Tag Manager, or do I have to choose one? You don't have to choose. Run PostHog directly via posthog-js for its own product analytics and session replay, and separately keep GTM loading whatever it already loads for GA4 or ad platforms. The trackEvent() wrapper above pushes to both posthog.capture() and window.dataLayer from one call site, so GTM can pick up any event you want it to see without a second, duplicate capture call anywhere in your components.

Is PostHog GDPR compliant out of the box? PostHog's EU Cloud region keeps data in EU infrastructure and PostHog itself offers the contractual pieces (a DPA, documented subprocessors) that GDPR compliance requires. But compliance isn't something a vendor hands you by default — it's the combination of choosing the EU region, gating capture behind real consent rather than assuming it, masking or excluding personal data from session replay, and not sending PII in event properties. The setup in this guide is what makes that combination actually true for your specific implementation, not something PostHog does automatically regardless of how you wire it up.

Why initialize PostHog in instrumentation-client.ts instead of a React component or provider? Because PostHog is a singleton once .init() has run — there's nothing a React component tree gives you that a plain module-level init doesn't, and instrumentation-client.ts runs before hydration, which means the SDK exists and is ready before your app's first render rather than racing a useEffect in some top-level component. A dedicated React context for PostHog is unnecessary complexity for something that's fundamentally a global, one-time setup step.

What happens to session replay if maskAllInputs is on but I forget to mask rendered text? Form field values stay masked correctly, but any personal data your app renders back onto the page as plain text — a name, an email, an address — will appear unmasked in the recording, because maskAllInputs only touches actual <input>/<textarea>/<select> elements, not arbitrary DOM text. That's exactly the gap .ph-mask and data-private close, and it's worth an explicit pass through your app looking for anywhere customer data gets echoed back before you turn recording on in production.

How do I know if my deploy pipeline has the same env-var problem described above? Check whichever step actually invokes next build — a Dockerfile RUN instruction, a CI build job, a Nixpacks/Vercel build step — and confirm the NEXT_PUBLIC_* variables your code references are genuinely present in that step's environment, not just in whatever .env file your container reads when it starts running afterward. If your build step gets its environment from a script, a secrets manager scope, or an allowlist rather than directly from your full .env file, that's the exact place a newly added variable can go missing without anything in your pipeline telling you.

Wrapping up

PostHog gets you real product analytics and session replay without the black-box feel of a CDN snippet, but the SDK install is the easy twenty percent of the work. The parts that actually matter for shipping it responsibly are wiring it into consent you already have instead of building a second system, masking session replay before real user data ever touches it, and — the one most guides skip entirely — understanding that NEXT_PUBLIC_* variables live and die at build time, not runtime, which means "the deploy succeeded" and "the feature actually works" are two different claims that need two different checks.

If you're setting this up and want a second pair of eyes on your deploy pipeline specifically — the build-vs-runtime env var split is the kind of thing that's obvious once you've been bitten by it once and invisible until then — that's exactly the kind of implementation work I take on for clients. Let me know in the comments if you run into something this guide didn't cover, and subscribe if you want more practical, real-implementation guides like this one.

Thanks, Matija

Tested with Next.js 16 (App Router) and posthog-js 1.409.x, deployed to a Docker-based production pipeline. Last updated 2026-08-02.

Why the demo version breaks in production

I needed a guided tour for Avtolibre, my vehicle marketplace built on Next.js and Payload CMS, covering search, an AI recommendation guide, vehicle filtering, and a leasing calculator across three locale-prefixed routes. The Driver.js quickstart handles a single static page fine: install the package, point a step at an element, call drive(). A tour that spans routes, locales, and device sizes has to also wait for hydration, target different desktop and mobile elements, persist across App Router navigation, respect reduced motion, and only fire analytics after consent. None of that comes from the library out of the box, and getting it right is what separates a demo from something you can ship.

The stack for this implementation:

• Next.js 16.2.6 and the App Router
• React 19.2
• Driver.js 1.8.0
• TypeScript
• next-intl
• Tailwind CSS and shadcn/ui
• Google Tag Manager
• Playwright

The finished tour has eight steps across three routes:

/{locale}
  Search
  AI guide

/{locale}/vehicles
  Filters
  Results
  Monthly cost (optional)

/{locale}/leasing-calculator
  Calculator inputs
  Estimated range
  Matching-vehicle search

It starts automatically once per tour version, can be dismissed and restarted manually, and resumes correctly after client-side navigation.

The architectural decisions that make this work

1. Existing layouts and pages stay Server Components.
2. A small Client Component owns Driver.js.
3. The JavaScript package is dynamically imported after hydration.
4. The vendor stylesheet loads once from the shared frontend layout.
5. Tour targets use stable data-tour attributes.
6. localStorage remembers whether a version was seen or completed.
7. sessionStorage carries the active step across routes.
8. Every Driver.js instance is destroyed before navigation or unmounting.
9. Analytics use stable IDs rather than translated copy.
10. Playwright verifies the complete browser behavior.

Here's the resulting file structure:

src/
  app/
    (frontend)/
      layout.tsx
  components/
    product-tour/
      ProductTourProvider.tsx
      ProductTourTrigger.tsx
      product-tour.css
  modules/
    marketplace/
      product-tour/
        analytics.ts
        definition.ts
        storage.ts
        types.ts
        validation.ts
        README.md
messages/
  de.json
  en.json
  sl.json
e2e/
  product-tour.spec.ts

Step 1: Install Driver.js with a pinned version

Use whatever package manager the project already uses. Avtolibre runs pnpm, and I pin Driver.js exactly rather than letting it float:

pnpm add driver.js@1.8.0 --save-exact

In a pnpm workspace, target the application package when running from the repository root:

pnpm --filter your-web-app add driver.js@1.8.0 --save-exact

Skip a CDN, next/script, custom Turbopack loaders, transpilePackages, or a Webpack fallback for this. Driver.js ships normal package exports, TypeScript declarations, JavaScript bundles, and a stylesheet, so none of that machinery is necessary.

Step 2: Load the CSS from the layout, and the JavaScript from the client

Import the Driver.js stylesheet once in the narrowest layout that covers the whole tour, and import any custom overrides right after it:

// File: src/app/(frontend)/layout.tsx
import "driver.js/dist/driver.css";
import "@/components/product-tour/product-tour.css";

export default function FrontendLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}

The layout stays a Server Component throughout. Driver.js's JavaScript loads later, from the client runtime, using a dynamic import:

const { driver } = await import("driver.js");

CSS belongs in the shared layout because it needs to be present the moment any tour target renders. Browser-only behavior belongs in a client island because it depends on hydration, window, and user interaction.

Step 3: Give the tour a stable DOM contract

Tour selectors are part of your UI contract, the same way a public API is. Target dedicated attributes rather than Tailwind classes, translated text, DOM position, or shadcn/ui internals, since any of those can change during a routine redesign and quietly break every step:

<form data-tour="marketplace-search">
  {/* Search controls */}
</form>

<section data-tour="vehicle-results">
  {/* Result cards */}
</section>

For content that only becomes usable after hydration, expose readiness explicitly:

"use client";

import { useEffect, useState } from "react";

export function SearchPanel() {
  const [tourReady, setTourReady] = useState(false);

  useEffect(() => {
    setTourReady(true);
  }, []);

  return (
    <form
      data-tour="marketplace-search"
      data-tour-ready={tourReady ? "true" : undefined}
    >
      {/* Search controls */}
    </form>
  );
}

The step can then require both identity and readiness:

element:
  '[data-tour="marketplace-search"][data-tour-ready="true"]';

Driver.js observes the DOM until this target appears, which is far more reliable than a fixed timeout guessing when hydration finished.

Watch for duplicate data-tour values on repeated cards. In this implementation, only the first vehicle with a monthly-payment value gets the optional target:

const monthlyPaymentTourIndex = vehicles.findIndex(
  (vehicle) => vehicle.monthlyPaymentFrom != null,
);

{vehicles.map((vehicle, index) => (
  <VehicleCard
    key={vehicle.id}
    vehicle={vehicle}
    tourTarget={
      index === monthlyPaymentTourIndex
        ? "vehicle-monthly-cost"
        : undefined
    }
  />
))}

Step 4: Define the tour types

Reuse Driver.js's exported DriveStep type rather than recreating the library's API from scratch:

// File: src/modules/marketplace/product-tour/types.ts
import type { DriveStep } from "driver.js";

export type ProductTourSource =
  | "automatic"
  | "manual"
  | "resume";

export type ProductTourSegment = {
  id: string;
  pathname: string;
  href?: string;
  steps: DriveStep[];
};

export type ProductTourDefinition = {
  id: string;
  version: number;
  autoStart?: boolean;
  segments: ProductTourSegment[];
};

export type ProductTourResumeState = {
  tourId: string;
  version: number;
  segmentIndex: number;
  stepIndex: number;
  source: ProductTourSource;
  savedAt: number;
};

export type StartProductTourOptions = {
  source?: ProductTourSource;
  restart?: boolean;
};

A segment maps to one route and one Driver.js instance. That boundary is what makes App Router navigation reliable: destroy the old instance, navigate, and create a fresh one on the destination route.

Step 5: Persist seen, completed, and resume state

Version every storage key. Bumping the version is what makes a materially changed tour eligible to run again for returning visitors:

product-tour:marketplace-overview:v2:seen
product-tour:marketplace-overview:v2:completed
product-tour:marketplace-overview:v2:resume

localStorage holds durable seen and completed state. sessionStorage carries the short-lived handoff between routes during a single visit:

// File: src/modules/marketplace/product-tour/storage.ts
import type {
  ProductTourDefinition,
  ProductTourResumeState,
} from "./types";

function storagePrefix(tour: ProductTourDefinition): string {
  return `product-tour:${tour.id}:v${tour.version}`;
}

export function productTourSeenKey(
  tour: ProductTourDefinition,
): string {
  return `${storagePrefix(tour)}:seen`;
}

export function productTourCompletedKey(
  tour: ProductTourDefinition,
): string {
  return `${storagePrefix(tour)}:completed`;
}

export function productTourResumeKey(
  tour: ProductTourDefinition,
): string {
  return `${storagePrefix(tour)}:resume`;
}

export function hasSeenTour(
  tour: ProductTourDefinition,
): boolean {
  try {
    return (
      window.localStorage.getItem(productTourSeenKey(tour)) === "1"
    );
  } catch {
    return false;
  }
}

export function markTourSeen(
  tour: ProductTourDefinition,
): void {
  try {
    window.localStorage.setItem(productTourSeenKey(tour), "1");
  } catch {
    // Storage can be unavailable in restricted browser contexts.
  }
}

export function markTourCompleted(
  tour: ProductTourDefinition,
): void {
  try {
    window.localStorage.setItem(
      productTourCompletedKey(tour),
      "1",
    );
  } catch {
    // The tour still works when persistence is unavailable.
  }
}

export function saveTourResumeState(
  tour: ProductTourDefinition,
  state: ProductTourResumeState,
): void {
  try {
    window.sessionStorage.setItem(
      productTourResumeKey(tour),
      JSON.stringify(state),
    );
  } catch {
    // Cross-route resume is unavailable when storage is blocked.
  }
}

function isProductTourSource(
  value: unknown,
): value is ProductTourResumeState["source"] {
  return (
    value === "automatic" ||
    value === "manual" ||
    value === "resume"
  );
}

export function parseTourResumeState(
  tour: ProductTourDefinition,
  value: string,
): ProductTourResumeState | null {
  try {
    const parsed = JSON.parse(
      value,
    ) as Partial<ProductTourResumeState>;

    if (
      parsed.tourId !== tour.id ||
      parsed.version !== tour.version ||
      !Number.isInteger(parsed.segmentIndex) ||
      (parsed.segmentIndex ?? -1) < 0 ||
      !Number.isInteger(parsed.stepIndex) ||
      (parsed.stepIndex ?? -1) < 0 ||
      !isProductTourSource(parsed.source) ||
      typeof parsed.savedAt !== "number"
    ) {
      return null;
    }

    return parsed as ProductTourResumeState;
  } catch {
    return null;
  }
}

export function readTourResumeState(
  tour: ProductTourDefinition,
): ProductTourResumeState | null {
  try {
    const value = window.sessionStorage.getItem(
      productTourResumeKey(tour),
    );
    if (!value) return null;

    const state = parseTourResumeState(tour, value);
    if (!state) clearTourResumeState(tour);
    return state;
  } catch {
    clearTourResumeState(tour);
    return null;
  }
}

export function clearTourResumeState(
  tour: ProductTourDefinition,
): void {
  try {
    window.sessionStorage.removeItem(productTourResumeKey(tour));
  } catch {
    // No action is required.
  }
}

export function resetTourStorage(
  tour: ProductTourDefinition,
): void {
  try {
    window.localStorage.removeItem(productTourSeenKey(tour));
    window.localStorage.removeItem(productTourCompletedKey(tour));
    window.sessionStorage.removeItem(productTourResumeKey(tour));
  } catch {
    // No action is required.
  }
}

These functions only touch browser storage when called directly. Keep storage reads out of module scope, and out of anything that produces server-rendered HTML.

Step 6: Keep analytics stable, consent-aware, and free of personal data

A translated step title makes a poor analytics identifier, since it changes with every copy edit. Give every step a stable data.id and send that value to GTM instead. Avtolibre already tracks a consent flag, so the analytics helper checks it before pushing anything:

// File: src/modules/marketplace/product-tour/analytics.ts
import type { ProductTourSource } from "./types";

export type ProductTourEvent =
  | "product_tour_started"
  | "product_tour_segment_started"
  | "product_tour_step_viewed"
  | "product_tour_route_transition"
  | "product_tour_completed"
  | "product_tour_dismissed"
  | "product_tour_error";

type ProductTourEventProperties = {
  tourId: string;
  tourVersion: number;
  source?: ProductTourSource;
  segmentId?: string;
  segmentIndex?: number;
  stepId?: string;
  stepIndex?: number;
  nextPathname?: string;
  errorMessage?: string;
};

export function trackProductTourEvent(
  event: ProductTourEvent,
  properties: ProductTourEventProperties,
): void {
  if (typeof window === "undefined") return;

  try {
    if (window.localStorage.getItem("analytics-consent") !== "true") {
      return;
    }
  } catch {
    return;
  }

  const analyticsWindow = window as Window & {
    dataLayer?: unknown[];
  };

  analyticsWindow.dataLayer ??= [];
  analyticsWindow.dataLayer.push({
    event,
    tour_id: properties.tourId,
    tour_version: properties.tourVersion,
    tour_source: properties.source,
    tour_segment_id: properties.segmentId,
    tour_segment_index: properties.segmentIndex,
    tour_step_id: properties.stepId,
    tour_step_index: properties.stepIndex,
    tour_next_pathname: properties.nextPathname,
    tour_error_message: properties.errorMessage,
  });
}

Swap analytics-consent for your own consent abstraction. Keep search text, vehicle IDs, financing inputs, form values, and any personal information out of tour events entirely.

Step 7: Build a localized, route-aware definition

The definition is a function because both the locale-prefixed paths and the translated copy are runtime inputs, not constants:

// File: src/modules/marketplace/product-tour/definition.ts
import type { DriveStep } from "driver.js";
import type { ProductTourDefinition } from "./types";

export type ProductTourCopy = {
  next: string;
  previous: string;
  finish: string;
  continue: string;
  progress: string;
  searchTitle: string;
  searchDescription: string;
  aiGuideTitle: string;
  aiGuideDescription: string;
  filtersTitle: string;
  filtersDescription: string;
  resultsTitle: string;
  resultsDescription: string;
  monthlyCostTitle: string;
  monthlyCostDescription: string;
  calculatorInputsTitle: string;
  calculatorInputsDescription: string;
  calculatorEstimateTitle: string;
  calculatorEstimateDescription: string;
  calculatorSearchTitle: string;
  calculatorSearchDescription: string;
};

function visibleVehicleFilters(): Element {
  const targets = [
    document.querySelector(
      '[data-tour="vehicle-filters-desktop"]',
    ),
    document.querySelector(
      '[data-tour="vehicle-filters-mobile"]' +
        '[data-tour-ready="true"]',
    ),
  ];

  const visibleTarget = targets.find(
    (target): target is HTMLElement =>
      target instanceof HTMLElement && target.offsetParent !== null,
  );

  // An empty result remains pending until waitForElement expires.
  return visibleTarget ?? (undefined as unknown as Element);
}

function step(
  id: string,
  element: DriveStep["element"],
  title: string,
  description: string,
  placement: NonNullable<DriveStep["popover"]> = {},
): DriveStep {
  return {
    element,
    waitForElement: 5000,
    data: { id },
    popover: { title, description, ...placement },
  };
}

export function createMarketplaceProductTour(
  locale: string,
  copy: ProductTourCopy,
): ProductTourDefinition {
  return {
    id: "marketplace-overview",
    version: 2,
    autoStart: true,
    segments: [
      {
        id: "discovery",
        pathname: `/${locale}`,
        steps: [
          step(
            "marketplace-search",
            '[data-tour="marketplace-search"]' +
              '[data-tour-ready="true"]',
            copy.searchTitle,
            copy.searchDescription,
            { side: "bottom", align: "center" },
          ),
          step(
            "ai-guide",
            '[data-tour="ai-guide"]' +
              '[data-tour-ready="true"]',
            copy.aiGuideTitle,
            copy.aiGuideDescription,
            { side: "top", align: "center" },
          ),
        ],
      },
      {
        id: "vehicle-results",
        pathname: `/${locale}/vehicles`,
        steps: [
          step(
            "vehicle-filters",
            visibleVehicleFilters,
            copy.filtersTitle,
            copy.filtersDescription,
            { side: "right", align: "start" },
          ),
          step(
            "vehicle-results",
            '[data-tour="vehicle-results"]',
            copy.resultsTitle,
            copy.resultsDescription,
            { side: "top", align: "center" },
          ),
          {
            ...step(
              "vehicle-monthly-cost",
              '[data-tour="vehicle-monthly-cost"]',
              copy.monthlyCostTitle,
              copy.monthlyCostDescription,
              { side: "left", align: "center" },
            ),
            waitForElement: 1000,
            skipMissingElement: true,
            data: {
              id: "vehicle-monthly-cost",
              optional: true,
            },
          },
        ],
      },
      {
        id: "leasing-calculator",
        pathname: `/${locale}/leasing-calculator`,
        steps: [
          step(
            "leasing-inputs",
            '[data-tour="leasing-inputs"]' +
              '[data-tour-ready="true"]',
            copy.calculatorInputsTitle,
            copy.calculatorInputsDescription,
            { side: "right", align: "start" },
          ),
          step(
            "leasing-estimate",
            '[data-tour="leasing-estimate"]' +
              '[data-tour-ready="true"]',
            copy.calculatorEstimateTitle,
            copy.calculatorEstimateDescription,
            { side: "left", align: "center" },
          ),
          step(
            "leasing-vehicle-search",
            '[data-tour="leasing-vehicle-search"]' +
              '[data-tour-ready="true"]',
            copy.calculatorSearchTitle,
            copy.calculatorSearchDescription,
            { side: "top", align: "center" },
          ),
        ],
      },
    ],
  };
}

Avtolibre ships localized Slovenian path segments (/vozila and /leasing-kalkulator). I used the English paths above to keep the example portable, but your route strings need to match exactly what usePathname() returns in your application.

Two details in this definition are worth calling out. The responsive filter step resolves whichever target is actually visible, because a desktop sidebar can exist in the DOM while hidden with CSS, and checking only for existence would target the wrong one. offsetParent !== null is a practical visibility test for that layout. And only the monthly-cost step is marked optional, on purpose: turning on skipMissingElement globally would silently hide any broken selector across the entire tour, turning a bug into an invisible product defect.

Step 8: Implement the client provider

This provider is the runtime. It owns the current Driver.js instance, automatic and manual starts, route-segment transitions, resume state, completion and dismissal, localization, reduced motion, analytics, and cleanup after navigation or unmounting. Here's the pattern in production, with a few imports shortened to generic module paths:

// File: src/components/product-tour/ProductTourProvider.tsx
"use client";

import {
  createContext,
  useCallback,
  useContext,
  useEffect,
  useMemo,
  useRef,
  useState,
} from "react";
import { usePathname, useRouter } from "next/navigation";
import { useTranslations } from "next-intl";
import type { Driver } from "driver.js";

import { trackProductTourEvent } from "@/modules/product-tour/analytics";
import {
  clearTourResumeState,
  hasSeenTour,
  markTourCompleted,
  markTourSeen,
  readTourResumeState,
  resetTourStorage,
  saveTourResumeState,
} from "@/modules/product-tour/storage";
import {
  createMarketplaceProductTour,
  type ProductTourCopy,
} from "@/modules/product-tour/definition";
import type {
  ProductTourSource,
  StartProductTourOptions,
} from "@/modules/product-tour/types";
import { validateProductTourDefinition } from "@/modules/product-tour/validation";

type ProductTourContextValue = {
  isActive: boolean;
  startTour: (
    options?: StartProductTourOptions,
  ) => Promise<void>;
  stopTour: () => void;
  resetTour: () => void;
};

const ProductTourContext =
  createContext<ProductTourContextValue | null>(null);

export function ProductTourProvider({
  locale,
  children,
}: Readonly<{
  locale: string;
  children: React.ReactNode;
}>) {
  const pathname = usePathname();
  const router = useRouter();
  const t = useTranslations("common.productTour");

  const copy = useMemo<ProductTourCopy>(
    () => ({
      next: t("next"),
      previous: t("previous"),
      finish: t("finish"),
      continue: t("continue"),
      progress: t.raw("progress") as string,
      searchTitle: t("steps.search.title"),
      searchDescription: t("steps.search.description"),
      aiGuideTitle: t("steps.aiGuide.title"),
      aiGuideDescription: t("steps.aiGuide.description"),
      filtersTitle: t("steps.filters.title"),
      filtersDescription: t("steps.filters.description"),
      resultsTitle: t("steps.results.title"),
      resultsDescription: t("steps.results.description"),
      monthlyCostTitle: t("steps.monthlyCost.title"),
      monthlyCostDescription: t("steps.monthlyCost.description"),
      calculatorInputsTitle: t("steps.calculatorInputs.title"),
      calculatorInputsDescription: t(
        "steps.calculatorInputs.description",
      ),
      calculatorEstimateTitle: t("steps.calculatorEstimate.title"),
      calculatorEstimateDescription: t(
        "steps.calculatorEstimate.description",
      ),
      calculatorSearchTitle: t("steps.calculatorSearch.title"),
      calculatorSearchDescription: t(
        "steps.calculatorSearch.description",
      ),
    }),
    [t],
  );

  const tour = useMemo(
    () => createMarketplaceProductTour(locale, copy),
    [copy, locale],
  );

  const pathnameRef = useRef(pathname);
  const driverRef = useRef<Driver | null>(null);
  const mountedRef = useRef(false);
  const startingRef = useRef(false);
  const routeTransitionRef = useRef(false);
  const completedRef = useRef(false);
  const dismissedRef = useRef(false);
  const teardownRef = useRef(false);
  const generationRef = useRef(0);
  const [isActive, setIsActive] = useState(false);

  useEffect(() => {
    pathnameRef.current = pathname;
  }, [pathname]);

  useEffect(() => {
    if (process.env.NODE_ENV === "production") return;
    const errors = validateProductTourDefinition(tour);
    if (errors.length > 0) {
      throw new Error(`[ProductTour] ${errors.join("; ")}`);
    }
  }, [tour]);

  useEffect(() => {
    mountedRef.current = true;

    return () => {
      mountedRef.current = false;
      teardownRef.current = true;
      generationRef.current += 1;

      if (driverRef.current?.isActive()) {
        driverRef.current.destroy();
      }

      driverRef.current = null;
    };
  }, []);

  const runSegment = useCallback(
    async (
      segmentIndex: number,
      startIndex: number,
      source: ProductTourSource,
    ): Promise<void> => {
      const segment = tour.segments[segmentIndex];

      if (!segment || segment.pathname !== pathnameRef.current) return;
      if (startingRef.current || driverRef.current?.isActive()) return;

      startingRef.current = true;
      routeTransitionRef.current = false;
      completedRef.current = false;
      dismissedRef.current = false;
      teardownRef.current = false;
      const generation = ++generationRef.current;

      markTourSeen(tour);

      try {
        const { driver } = await import("driver.js");

        if (
          !mountedRef.current ||
          generation !== generationRef.current ||
          segment.pathname !== pathnameRef.current
        ) {
          return;
        }

        const hasNextSegment =
          segmentIndex < tour.segments.length - 1;
        const reducedMotion = window.matchMedia(
          "(prefers-reduced-motion: reduce)",
        ).matches;

        const instance = driver({
          animate: !reducedMotion,
          duration: reducedMotion ? 0 : 300,
          smoothScroll: !reducedMotion,
          showProgress: true,
          progressText: copy.progress,
          nextBtnText: copy.next,
          prevBtnText: copy.previous,
          doneBtnText: hasNextSegment
            ? copy.continue
            : copy.finish,
          allowClose: true,
          allowScroll: true,
          allowKeyboardControl: true,
          overlayColor: "#000000",
          overlayOpacity: 0.55,
          stagePadding: 8,
          stageRadius: 12,
          popoverOffset: 12,
          popoverClass: "app-product-tour-popover",
          waitForElement: 5000,
          skipMissingElement: false,
          steps: segment.steps,

          onHighlightStarted: (
            _element,
            activeStep,
            { index },
          ) => {
            const stepIndex = index ?? 0;
            const stepId =
              typeof activeStep.data?.id === "string"
                ? activeStep.data.id
                : undefined;

            saveTourResumeState(tour, {
              tourId: tour.id,
              version: tour.version,
              segmentIndex,
              stepIndex,
              source,
              savedAt: Date.now(),
            });

            trackProductTourEvent("product_tour_step_viewed", {
              tourId: tour.id,
              tourVersion: tour.version,
              source,
              segmentId: segment.id,
              segmentIndex,
              stepId,
              stepIndex,
            });
          },

          onDoneClick: (
            _element,
            _step,
            { driver: activeDriver },
          ) => {
            if (hasNextSegment) {
              const nextSegment = tour.segments[segmentIndex + 1];

              if (!nextSegment) {
                activeDriver.destroy();
                return;
              }

              saveTourResumeState(tour, {
                tourId: tour.id,
                version: tour.version,
                segmentIndex: segmentIndex + 1,
                stepIndex: 0,
                source: "resume",
                savedAt: Date.now(),
              });
              routeTransitionRef.current = true;

              trackProductTourEvent(
                "product_tour_route_transition",
                {
                  tourId: tour.id,
                  tourVersion: tour.version,
                  source,
                  segmentId: segment.id,
                  segmentIndex,
                  nextPathname: nextSegment.pathname,
                },
              );

              activeDriver.destroy();
              router.push(nextSegment.href ?? nextSegment.pathname);
              return;
            }

            completedRef.current = true;
            markTourCompleted(tour);
            clearTourResumeState(tour);

            trackProductTourEvent("product_tour_completed", {
              tourId: tour.id,
              tourVersion: tour.version,
              source,
              segmentId: segment.id,
              segmentIndex,
            });

            activeDriver.destroy();
          },

          onDestroyStarted: (
            _element,
            _step,
            { driver: activeDriver, index },
          ) => {
            dismissedRef.current = true;
            driverRef.current = null;
            if (mountedRef.current) setIsActive(false);
            clearTourResumeState(tour);

            trackProductTourEvent("product_tour_dismissed", {
              tourId: tour.id,
              tourVersion: tour.version,
              source,
              segmentId: segment.id,
              segmentIndex,
              stepIndex: index,
            });

            // A custom onDestroyStarted owns final teardown.
            activeDriver.destroy();
          },

          onDestroyed: (_element, _step, { index }) => {
            driverRef.current = null;
            if (mountedRef.current) setIsActive(false);

            if (
              routeTransitionRef.current ||
              completedRef.current ||
              dismissedRef.current ||
              teardownRef.current
            ) {
              return;
            }

            clearTourResumeState(tour);
            trackProductTourEvent("product_tour_dismissed", {
              tourId: tour.id,
              tourVersion: tour.version,
              source,
              segmentId: segment.id,
              segmentIndex,
              stepIndex: index,
            });
          },
        });

        driverRef.current = instance;
        setIsActive(true);

        trackProductTourEvent("product_tour_segment_started", {
          tourId: tour.id,
          tourVersion: tour.version,
          source,
          segmentId: segment.id,
          segmentIndex,
        });

        instance.drive(
          Math.min(startIndex, segment.steps.length - 1),
        );
      } catch (error) {
        const errorMessage =
          error instanceof Error
            ? error.message
            : "Unknown Driver.js error";

        driverRef.current = null;
        clearTourResumeState(tour);
        if (mountedRef.current) setIsActive(false);

        trackProductTourEvent("product_tour_error", {
          tourId: tour.id,
          tourVersion: tour.version,
          source,
          segmentId: segment.id,
          segmentIndex,
          errorMessage,
        });

        console.error("[ProductTour] Unable to start tour", error);
      } finally {
        startingRef.current = false;
      }
    },
    [copy, router, tour],
  );

  const startTour = useCallback(
    async (
      options: StartProductTourOptions = {},
    ): Promise<void> => {
      if (startingRef.current || driverRef.current?.isActive()) return;

      const source = options.source ?? "manual";
      const firstSegment = tour.segments[0];
      if (!firstSegment) return;

      clearTourResumeState(tour);
      trackProductTourEvent("product_tour_started", {
        tourId: tour.id,
        tourVersion: tour.version,
        source,
      });

      if (firstSegment.pathname !== pathnameRef.current) {
        markTourSeen(tour);
        saveTourResumeState(tour, {
          tourId: tour.id,
          version: tour.version,
          segmentIndex: 0,
          stepIndex: 0,
          source: "resume",
          savedAt: Date.now(),
        });
        router.push(firstSegment.href ?? firstSegment.pathname);
        return;
      }

      await runSegment(0, 0, source);
    },
    [router, runSegment, tour],
  );

  const stopTour = useCallback(() => {
    generationRef.current += 1;
    routeTransitionRef.current = false;
    clearTourResumeState(tour);
    if (driverRef.current?.isActive()) driverRef.current.destroy();
    driverRef.current = null;
    setIsActive(false);
  }, [tour]);

  const resetTour = useCallback(() => {
    generationRef.current += 1;
    if (driverRef.current?.isActive()) driverRef.current.destroy();
    driverRef.current = null;
    setIsActive(false);
    resetTourStorage(tour);
  }, [tour]);

  useEffect(() => {
    const resumeState = readTourResumeState(tour);
    if (!resumeState) return;

    const segment = tour.segments[resumeState.segmentIndex];
    if (!segment || segment.pathname !== pathname) return;

    if (resumeState.stepIndex >= segment.steps.length) {
      clearTourResumeState(tour);
      return;
    }

    clearTourResumeState(tour);
    void runSegment(
      resumeState.segmentIndex,
      resumeState.stepIndex,
      "resume",
    );
  }, [pathname, runSegment, tour]);

  useEffect(() => {
    if (!tour.autoStart || hasSeenTour(tour)) return;
    const firstSegment = tour.segments[0];
    if (!firstSegment || firstSegment.pathname !== pathname) return;
    void runSegment(0, 0, "automatic");
  }, [pathname, runSegment, tour]);

  const value = useMemo(
    () => ({ isActive, startTour, stopTour, resetTour }),
    [isActive, resetTour, startTour, stopTour],
  );

  return (
    <ProductTourContext.Provider value={value}>
      {children}
    </ProductTourContext.Provider>
  );
}

export function useProductTour(): ProductTourContextValue {
  const context = useContext(ProductTourContext);
  if (!context) {
    throw new Error(
      "useProductTour must be used within ProductTourProvider",
    );
  }
  return context;
}

What each ref is guarding against

Every ref in this provider closes a specific race condition or analytics ambiguity:

The generation check earns its place especially in React development mode, where a dynamic import can resolve after the component has already unmounted, or after the user has already stopped the tour. Incrementing the generation counter invalidates that stale continuation before it can touch state.

Explicit destroy() calls matter for the same reason. Once you override Driver.js's lifecycle hooks, your callback becomes responsible for that behavior. This provider calls destroy() when a route segment ends, when the final step completes, from the custom destroy-start callback, when the user stops or resets the tour, and when the provider unmounts. Skipping any of those leaves a stale overlay or event listener behind after navigation.

Step 9: Add the manual restart trigger

Automatic start should never remove the manual path, since a visitor might dismiss the tour, finish it, or want to show it to a colleague later:

// File: src/components/product-tour/ProductTourTrigger.tsx
"use client";

import { CircleHelp } from "lucide-react";
import { useTranslations } from "next-intl";
import { useEffect, useState } from "react";
import { Button } from "@/components/ui/button";
import { useProductTour } from "./ProductTourProvider";

export function ProductTourTrigger({
  compact = false,
}: {
  compact?: boolean;
}) {
  const t = useTranslations("common.productTour");
  const { isActive, startTour } = useProductTour();
  const [ready, setReady] = useState(false);

  useEffect(() => {
    setReady(true);
  }, []);

  return (
    <Button
      type="button"
      variant="outline"
      size={compact ? "icon" : "sm"}
      disabled={!ready || isActive}
      data-tour-ready={ready ? "true" : undefined}
      aria-label={isActive ? t("active") : t("trigger")}
      title={
        compact
          ? isActive
            ? t("active")
            : t("trigger")
          : undefined
      }
      onClick={() =>
        void startTour({ source: "manual", restart: true })
      }
    >
      <CircleHelp aria-hidden="true" />
      {compact ? (
        <span className="sr-only">{t("trigger")}</span>
      ) : isActive ? (
        t("active")
      ) : (
        t("trigger")
      )}
    </Button>
  );
}

Render the labeled button on larger screens and the compact icon on smaller ones, keeping the accessible name intact either way.

Step 10: Mount the provider at the narrowest shared boundary

The provider needs to wrap every route the tour touches, and nothing beyond that. On Avtolibre, the public marketplace gets the provider while the authenticated back office does not:

// Server Component
export async function LocaleChromeGate({
  locale,
  children,
}: {
  locale: string;
  children: React.ReactNode;
}) {
  const pathname = await readRequestPathname();

  if (isOfficePath(pathname)) {
    return <div>{children}</div>;
  }

  return (
    <ProductTourProvider locale={locale}>
      <div className="flex min-h-screen flex-col">
        <MarketplaceNavbar locale={locale} />
        <main className="flex-1">{children}</main>
        <Footer />
      </div>
      <CookieConsent />
    </ProductTourProvider>
  );
}

Passing Server Component content as children through a Client Component boundary works fine here. The pages underneath never need "use client" themselves just because Driver.js highlights elements inside them.

Step 11: Theme Driver.js with your own design tokens

Driver.js adds its own classes to the DOM, which plain CSS can theme against existing shadcn variables:

/* File: src/components/product-tour/product-tour.css */
.driver-popover.app-product-tour-popover {
  --driver-popover-font-family:
    var(--font-sans, ui-sans-serif, system-ui, sans-serif);

  /* Driver.js puts the SVG overlay at z-index 10000 inline. */
  z-index: 10001;
  width: min(360px, calc(100vw - 32px));
  max-width: 360px;
  padding: 16px;
  border: 1px solid var(--border);
  border-radius: calc(var(--radius) + 4px);
  background: var(--popover);
  color: var(--popover-foreground);
  box-shadow: var(--shadow-xl);
}

.driver-popover.app-product-tour-popover
  .driver-popover-title {
  color: var(--popover-foreground);
  font-size: 1rem;
  font-weight: 700;
  line-height: 1.4;
}

.driver-popover.app-product-tour-popover
  .driver-popover-description,
.driver-popover.app-product-tour-popover
  .driver-popover-progress-text {
  color: var(--muted-foreground);
}

.driver-popover.app-product-tour-popover
  .driver-popover-description {
  font-size: 0.875rem;
  line-height: 1.55;
}

.driver-popover.app-product-tour-popover
  .driver-popover-progress-text {
  font-size: 0.75rem;
}

.driver-popover.app-product-tour-popover
  .driver-popover-footer-btn {
  min-height: 36px;
  padding-inline: 12px;
  border: 1px solid var(--border);
  border-radius: var(--radius);
  background: var(--secondary);
  color: var(--secondary-foreground);
  font-family: inherit;
  font-size: 0.875rem;
  font-weight: 600;
  text-shadow: none;
}

.driver-popover.app-product-tour-popover
  .driver-popover-next-btn {
  border-color: var(--primary);
  background: var(--primary);
  color: var(--primary-foreground);
}

.driver-popover.app-product-tour-popover
  .driver-popover-close-btn {
  color: var(--muted-foreground);
}

.driver-popover.app-product-tour-popover
  .driver-popover-close-btn:hover {
  color: var(--foreground);
}

.driver-popover.app-product-tour-popover
  .driver-popover-footer-btn:focus-visible,
.driver-popover.app-product-tour-popover
  .driver-popover-close-btn:focus-visible {
  outline: 2px solid var(--ring);
  outline-offset: 2px;
}

@media (max-width: 640px) {
  .driver-popover.app-product-tour-popover {
    width: calc(100vw - 24px);
    max-width: none;
    padding: 14px;
  }
}

@media (prefers-reduced-motion: reduce) {
  .driver-popover,
  .driver-overlay,
  .driver-active-element {
    transition-duration: 0s !important;
    animation-duration: 0s !important;
  }
}

Cross-check this against your full z-index system, and test the tour with sticky headers, dialogs, sheets, cookie banners, chat widgets, toasts, and mobile navigation all present at once.

Step 12: Validate the definition during development

A typo in a selector deserves to fail loudly before it reaches a demo. A small structural validator catches mistakes TypeScript can't:

// File: src/modules/marketplace/product-tour/validation.ts
import type { ProductTourDefinition } from "./types";

export function validateProductTourDefinition(
  tour: ProductTourDefinition,
): string[] {
  const errors: string[] = [];
  const segmentIds = new Set<string>();
  const pathnames = new Set<string>();
  const stepIds = new Set<string>();

  if (!tour.id.trim()) errors.push("Tour ID must not be empty");
  if (!Number.isInteger(tour.version) || tour.version < 1) {
    errors.push("Tour version must be a positive integer");
  }
  if (tour.segments.length === 0) {
    errors.push("Tour must include at least one segment");
  }

  tour.segments.forEach((segment, segmentIndex) => {
    if (!segment.id.trim()) {
      errors.push(`Segment ${segmentIndex} must have an ID`);
    }
    if (segmentIds.has(segment.id)) {
      errors.push(`Duplicate segment ID: ${segment.id}`);
    }
    segmentIds.add(segment.id);

    if (!segment.pathname.startsWith("/")) {
      errors.push(
        `Segment ${segment.id} pathname must start with /`,
      );
    }
    if (pathnames.has(segment.pathname)) {
      errors.push(
        `Duplicate segment pathname: ${segment.pathname}`,
      );
    }
    pathnames.add(segment.pathname);

    if (segment.steps.length === 0) {
      errors.push(`Segment ${segment.id} must include a step`);
    }

    const selectors = new Set<string>();

    segment.steps.forEach((tourStep, stepIndex) => {
      const stepId =
        typeof tourStep.data?.id === "string"
          ? tourStep.data.id.trim()
          : "";

      if (!stepId) {
        errors.push(
          `Segment ${segment.id} step ${stepIndex} must have a data.id`,
        );
      }
      if (stepId && stepIds.has(stepId)) {
        errors.push(`Duplicate step ID: ${stepId}`);
      }
      if (stepId) stepIds.add(stepId);

      if (typeof tourStep.element === "string") {
        if (selectors.has(tourStep.element)) {
          errors.push(
            `Duplicate selector in segment ${segment.id}: ` +
              tourStep.element,
          );
        }
        selectors.add(tourStep.element);
      }

      if (
        stepIndex === segment.steps.length - 1 &&
        tourStep.popover?.onDoneClick
      ) {
        errors.push(
          `Segment ${segment.id} final step must not override onDoneClick`,
        );
      }
    });
  });

  return errors;
}

Run this from the provider outside production only. It checks structure, not actual DOM presence, since Suspense and portals can render a target later than the validator would expect. Browser tests are what confirm real DOM behavior, which is what Step 14 covers.

Step 13: Add the translation keys

The provider reads every label and every step's copy from one namespace. Here's a shortened English example:

{
  "common": {
    "productTour": {
      "trigger": "Guided tour",
      "active": "Tour in progress",
      "next": "Next",
      "previous": "Back",
      "continue": "Continue",
      "finish": "Finish",
      "progress": "{{current}} of {{total}}",
      "steps": {
        "search": {
          "title": "Find the right vehicle",
          "description": "Choose a vehicle type or describe the model you are looking for."
        },
        "aiGuide": {
          "title": "Recommendations for your needs",
          "description": "The guide narrows the available vehicles with a few short questions."
        },
        "filters": {
          "title": "Refine your selection",
          "description": "Filter by brand, price, monthly payment, and other important details."
        }
      }
    }
  }
}

Keep analytics IDs out of the translation files entirely. Copy changes often, and the event contract you rely on for reporting should stay fixed regardless. My guide on Next.js internationalization architecture covers the three-layer next-intl setup this tour's translations sit on top of, if you're wiring up locales from scratch.

Step 14: Test the real browser behavior

Unit tests cover versioned keys, corrupted resume state, and definition validation well. They can't confirm that the overlay actually lands on the correct responsive element, which is exactly what Playwright is for:

// File: e2e/product-tour.spec.ts
import { expect, test } from "@playwright/test";

test.describe("marketplace product tour", () => {
  test.beforeEach(async ({ page }) => {
    await page.addInitScript(() => {
      window.localStorage.clear();
      window.sessionStorage.clear();
    });
    await page.goto("/en", { waitUntil: "domcontentloaded" });
  });

  test(
    "starts automatically, dismisses, and restarts manually",
    async ({ page }) => {
      await expect(page.locator(".driver-popover")).toBeVisible();
      await expect(
        page.locator('[data-tour="marketplace-search"]'),
      ).toHaveClass(/driver-active-element/);

      await page.locator(".driver-popover-close-btn").click();
      await expect(page.locator(".driver-popover")).toHaveCount(0);

      await page
        .getByRole("button", { name: "Guided tour" })
        .click();
      await expect(page.locator(".driver-popover")).toBeVisible();
    },
  );

  test("resumes after App Router navigation", async ({ page }) => {
    await page.locator(".driver-popover-next-btn").click();
    await page.locator(".driver-popover-next-btn").click();

    await expect(page).toHaveURL(/\/en\/vehicles$/);
    await expect(page.locator(".driver-popover")).toBeVisible();
  });

  test("uses the mobile filter target", async ({ page }) => {
    await page.setViewportSize({ width: 390, height: 844 });
    await page.evaluate(() => {
      window.localStorage.clear();
      window.sessionStorage.clear();
    });
    await page.reload({ waitUntil: "domcontentloaded" });

    await expect(page.locator(".driver-popover")).toBeVisible();
    await page.locator(".driver-popover-next-btn").click();
    await page.locator(".driver-popover-next-btn").click();

    await expect(page).toHaveURL(/\/en\/vehicles$/);
    await expect(
      page.locator('[data-tour="vehicle-filters-mobile"]'),
    ).toHaveClass(/driver-active-element/);
  });

  test("respects reduced motion", async ({ page }) => {
    await page.emulateMedia({ reducedMotion: "reduce" });
    await page.evaluate(() => {
      window.localStorage.clear();
      window.sessionStorage.clear();
    });
    await page.reload({ waitUntil: "domcontentloaded" });

    await expect(page.locator(".driver-popover")).toBeVisible();
    await expect(page.locator("body")).toHaveClass(/driver-simple/);

    const duration = await page
      .locator(".driver-popover")
      .evaluate(
        (popover) =>
          window.getComputedStyle(popover).animationDuration,
      );

    expect(duration).toBe("0s");
  });
});

My full Avtolibre suite also covers completion storage and filters console errors for hydration, window is not defined, and document is not defined failures. Run the narrow tests first:

pnpm exec vitest run src/tests/unit/product-tour.test.ts
pnpm exec playwright test product-tour.spec.ts --project=default --workers=1

Follow up with the application's normal lint, type-check, and production build commands before merging.

Common mistakes to check for

Accessibility and privacy checklist

Before shipping a tour like this, confirm:

• Escape and the close button both dismiss the tour.
• Previous, Next, and Finish are all keyboard reachable.
• Focus indicators stay visible throughout.
• Popovers fit at mobile widths and at 200% zoom.
• Reduced-motion users get no animated transition.
• The tour never traps a user permanently.
• Cookie, privacy, or emergency controls stay accessible while the tour runs.
• Translated copy holds sufficient contrast in every supported theme.
• Analytics events carry no personal, search, or financial data.
• Any CMS or user-provided HTML gets sanitized before it reaches popover copy.

Adding another step later

Whenever the tour changes, work through this sequence:

1. Add one unique data-tour="..." attribute to a stable rendered element.
2. Add the matching step with a globally unique data.id.
3. Add translated title and description keys for every locale.
4. Decide whether the target needs data-tour-ready or a longer waitForElement.
5. Mark it optional only when its absence is genuinely valid product behavior.
6. Update the validator and the Playwright coverage.
7. Bump the tour version whenever order or meaning changes materially.
8. Test desktop, mobile, reduced motion, dismissal, restart, completion, and cross-route resume.

FAQ

Does Driver.js support React out of the box? No. Driver.js is a vanilla JavaScript library with no React bindings, which is exactly why this implementation wraps it in a Client Component that manages its own lifecycle, refs, and cleanup by hand.

Why dynamically import Driver.js instead of importing it normally? A normal top-level import pulls the library into your initial client bundle even on routes where the tour never runs. A dynamic import inside an effect or a click handler defers that cost until the tour actually starts.

How do I stop the tour from re-running for every returning visitor? Store a seen flag in localStorage, keyed by tour ID and version, and check it before auto-starting. Bump the version number only when the tour changes enough to warrant showing it again.

What happens if a target element never appears? Driver.js waits up to the waitForElement duration and then either fails the step or skips it, depending on skipMissingElement. Set that flag per step rather than globally, so a genuinely broken selector still surfaces as an error instead of silently vanishing.

Can the tour run across multiple routes in Next.js App Router? Yes, by treating each route as its own segment with its own Driver.js instance. Save the target segment and step index to sessionStorage before navigating, destroy the current instance, and start a new one once usePathname() matches the destination.

Wrapping up

This structure keeps the strengths of the App Router intact. Pages stay server-rendered, Driver.js stays a small browser-only enhancement, Next.js keeps owning navigation, and state stays explicit and versioned. Responsive differences get resolved on purpose, analytics respect consent, and the Playwright suite proves the overlay actually appears and survives the full route sequence rather than just working in a local demo.

Let me know in the comments if you have questions, and subscribe for more practical development guides.

Further reading

• Driver.js installation
• Driver.js configuration
• Driver.js theming
• Next.js Server and Client Components
• Next.js useRouter
• Next.js usePathname

Thanks, Matija

I picked up a six-button mini keyboard for around €25 with exactly this in mind. Out of the box it had no configuration software and simply typed letters when pressed. I used Karabiner-Elements to turn four of those buttons into direct shortcuts for Cursor, Claude, Codex, and native macOS Dictation. This guide walks through the exact setup, including the device-matching step that keeps the remapped letters from also changing on your MacBook's own keyboard.

What you need

• A Mac
• A small Bluetooth or USB mini keyboard
• Karabiner-Elements
• The keyboard shortcuts your preferred applications already use

The mini keyboard does not need official Mac support or bundled software. macOS only needs to recognize its buttons as standard keyboard events, and Karabiner takes it from there.

The finished layout

Here is how the four lower buttons ended up mapped:

Karabiner replaces these letters with the assigned shortcuts only when they arrive from the mini keyboard specifically. The same letters typed on the MacBook's built-in keyboard keep working exactly as they always have.

Step 1: Connect the mini keyboard and record its raw output

Pair the device first, through System Settings → Bluetooth.

Once it's connected, open a plain text editor and press every button on the keypad, noting exactly what each one types. My device produced plain letters with no special codes: the two top buttons typed D and A, the middle row typed E and B, and the bottom row typed F and C.

Cheap mini keyboards commonly present themselves to macOS as ordinary keyboards rather than as true programmable macro pads. That's completely fine for this project; Karabiner works from whatever raw keystrokes the device already sends.

Step 2: Install Karabiner-Elements

Download and install Karabiner-Elements from the link above. During installation, macOS will prompt for a few permissions:

• Input Monitoring
• Accessibility access
• The Karabiner Driver Extension

Grant all three. Karabiner can display and edit rules without them, but it needs Input Monitoring and the driver extension to actually intercept keystrokes before they reach the rest of the system.

If Karabiner shows "Waiting for a connection to the IOKit service," check System Settings → General → Login Items & Extensions → Driver Extensions and confirm the Karabiner virtual HID driver is enabled there. Restarting the Karabiner background services, or in some cases restarting the Mac entirely, is sometimes necessary right after the first install.

Step 3: Identify the mini keyboard's device signature

Open Karabiner-EventViewer, included with the Karabiner-Elements install, and press a button on the mini keyboard. EventViewer will show:

• Vendor ID
• Product ID
• The key code the button actually produces

My keyboard identified itself as product MINI-KEYBOARD, vendor ID 1452, product ID 556. Your device will almost certainly report different numbers, so pull your own values from EventViewer rather than reusing these.

This device-specific matching step matters more than it might look. Without it, a rule that remaps the F key would remap F everywhere, including on your MacBook's built-in keyboard, not just on the mini keypad.

Step 4: Enable Modify Events for the device

In Karabiner-Elements, open the Devices tab, find the mini keyboard in the list, and enable Modify events for it.

Some inexpensive keypads register themselves with macOS as both a keyboard and a pointing device simultaneously. If Karabiner detects button presses in EventViewer but your rules never fire, check that event modification is enabled for the full composite device, not just the keyboard portion of it. My device needed identifiers matching this shape:

// File: identifiers used to match the composite device
{
  "is_keyboard": true,
  "is_pointing_device": true,
  "product_id": 556,
  "vendor_id": 1452
}

Step 5: Design the shortcut mappings

Karabiner can turn one physical button press into any combination of keys, including modifier combinations your applications wouldn't otherwise let you trigger from a single key.

Before writing any Karabiner rules, test each target shortcut manually on the MacBook keyboard first. Confirming that Control+M actually opens the right panel in Cursor, or that Command+D actually triggers the intended Claude action, saves time over debugging the shortcut and the Karabiner rule at once. Once a shortcut is confirmed working manually, the mapping table above becomes the spec for the rule itself.

Step 6: Write the Karabiner Complex Modification

Karabiner rules live in the app's Complex Modifications editor, but the underlying format is JSON, which makes it easy to write directly. Here is the complete rule for the four buttons on my device:

// File: karabiner_mini_keyboard_ai_shortcuts.json
{
  "description": "MINI-KEYBOARD: AI and dictation shortcuts",
  "manipulators": [
    {
      "type": "basic",
      "conditions": [
        {
          "type": "device_if",
          "identifiers": [
            {
              "vendor_id": 1452,
              "product_id": 556
            }
          ]
        }
      ],
      "from": {
        "key_code": "e"
      },
      "to": [
        {
          "key_code": "m",
          "modifiers": ["left_control"]
        }
      ]
    },
    {
      "type": "basic",
      "conditions": [
        {
          "type": "device_if",
          "identifiers": [
            {
              "vendor_id": 1452,
              "product_id": 556
            }
          ]
        }
      ],
      "from": {
        "key_code": "b"
      },
      "to": [
        {
          "consumer_key_code": "dictation"
        }
      ]
    },
    {
      "type": "basic",
      "conditions": [
        {
          "type": "device_if",
          "identifiers": [
            {
              "vendor_id": 1452,
              "product_id": 556
            }
          ]
        }
      ],
      "from": {
        "key_code": "f"
      },
      "to": [
        {
          "key_code": "d",
          "modifiers": [
            "fn",
            "left_control",
            "left_shift"
          ]
        }
      ]
    },
    {
      "type": "basic",
      "conditions": [
        {
          "type": "device_if",
          "identifiers": [
            {
              "vendor_id": 1452,
              "product_id": 556
            }
          ]
        }
      ],
      "from": {
        "key_code": "c"
      },
      "to": [
        {
          "key_code": "d",
          "modifiers": ["left_command"]
        }
      ]
    }
  ]
}

Each manipulator follows the same shape: a device_if condition scoped to the exact vendor and product ID from Step 3, a from key code matching the raw letter the button sends, and a to block defining the actual shortcut to emit. The device_if condition is what keeps this rule from affecting your MacBook keyboard at all. Replace the vendor ID, product ID, input key codes, and output shortcuts with the values that match your own hardware and applications, then import the rule through Karabiner-Elements' Complex Modifications tab.

Step 7: Test each mapping individually

Work through each button one at a time rather than testing all four at once:

1. Click into the application the button is meant to control.
2. Press the mini-keyboard button once.
3. Confirm the expected action actually starts.
4. Confirm the original letter was not inserted anywhere.
5. Confirm the same letter still types normally on the MacBook keyboard.

If a button keeps typing its original letter instead of triggering the shortcut, check Karabiner's log for whether it describes the device as grabbed. Karabiner-EventViewer detecting button presses is a separate thing from Karabiner actually capturing the device; a rule only takes effect once the device is grabbed.

FAQ

Does the mini keyboard need to advertise itself as a programmable macro pad? No. Karabiner works from whatever raw keyboard events macOS already receives from the device. A keypad that simply types plain letters is enough as a starting point.

Why remap by vendor ID and product ID instead of just the key code? Matching only the key code would remap that letter everywhere, including on the built-in MacBook keyboard. Scoping each rule to the mini keyboard's specific vendor and product ID keeps the remapping isolated to that one device.

What if Karabiner shows the button press in EventViewer but the rule never fires? Check the Devices tab and confirm Modify Events is enabled for the mini keyboard. Composite devices that register as both a keyboard and a pointing device sometimes need this toggle set explicitly before rules apply.

Can one button trigger more than a simple two-key shortcut? Yes. The to array in a Karabiner manipulator accepts any key code plus any combination of modifiers, so a single button press can reproduce shortcuts your applications only expose through multi-key combinations.

What happens if I switch which AI tool a button controls later? Editing the rule's to block for that manipulator and reimporting it is all that's needed. The mapping lives entirely in the JSON rule, not on the hardware, so reassigning a button takes a few minutes.

Wrapping up

A €25 mini keyboard combined with Karabiner-Elements produces a genuinely useful AI shortcut pad: one-touch dictation, dedicated buttons for Cursor, Claude, and Codex, and mappings that stay entirely under your own control rather than a vendor's software. The device-matching step in the Complex Modification is what makes it safe to remap ordinary letters without disturbing your regular typing, and the same JSON rule can be edited in minutes whenever your toolset changes. The buttons that control Codex, Claude, and Cursor today can just as easily control a different editor, assistant, or automation tool tomorrow.

Let me know in the comments if you have questions, and subscribe for more practical development guides.

Thanks, Matija

I run five Cursor windows across separate client and internal projects most days, and the bottleneck was never my local CPU. It was how much of my work I could keep visible at once. Once I moved my actual development environment onto a Hetzner server, I stopped caring what processor sat on my desk and started caring about how many monitors it could drive.

This guide walks through the architecture, what actually consumes local resources, and how to pick hardware, including a specific low-cost GPU that solves the multi-monitor problem cleanly.

The Two-Machine Architecture

The setup splits into a local client and a remote development server.

Local client

Your desk machine runs Ubuntu, your editor (Cursor or VS Code), SSH terminals, a browser, and communication apps. It also drives your physical monitors, keyboard, and mouse. Nothing here needs to be fast. It just needs to render windows reliably.

Remote development server

The VPS runs your Git repositories, your Node.js or Python runtime, your dev servers, type checking, builds, Docker containers, databases, Redis, and any AI agent terminal commands. This is where the actual work happens.

My remote machine is a Hetzner server with an AMD Ryzen 5 3600, 64 GB of RAM, and SSD storage. That's far more capacity than my local client will ever touch, because the client's job is display, not computation.

Remote SSH extensions in VS Code and Cursor install a small server component on the remote machine, which lets the editor interface stay local while every command you run executes on the remote filesystem. Your local machine becomes a terminal in the original sense of the word: a window into compute that lives elsewhere.

Why This Fits AI Coding Specifically

Traditional development tends to center on one active editor window where you write and review code continuously. AI-assisted development spreads that attention across several windows at once.

On a typical day I have Cursor open on a client website, an internal proposal system, my own business site, and a demo project, sometimes with a second worktree of another project alongside them. The limiting factor is how much I can supervise, not how fast I can type. A wider desktop surface directly increases how many active AI agents I can watch and steer at the same time.

One monitor holds the primary Cursor agent. Another shows the running site. A third holds logs and terminals. A fourth holds documentation or the CMS admin panel. Extra monitors here produce more practical value than a faster local CPU.

What Actually Runs Locally

Moving development to a VPS still leaves real work for the local machine. Cursor and VS Code are Electron apps, so every open window needs local memory for rendering, chat history, and background processes.

On my current setup, five Cursor windows together use roughly 3.5 to 3.8 GiB of local RAM:

About 0.5 GiB of that is shared Cursor overhead distributed across windows, so each workspace's actual footprint runs closer to 0.47 to 0.77 GiB.

A realistic local memory budget looks like this:

Ubuntu 26.04 LTS lists 6 GB as the minimum for a comfortable desktop, but that figure assumes light usage. Running several Electron apps alongside a dozen browser tabs pushes well past that. Here's where I landed on RAM tiers:

The monitor count itself barely touches system memory. Framebuffers are cheap. Editor windows, browser tabs, and desktop apps are what eat RAM.

The GPU Matters More Than the CPU

The first questions to ask about a thin client aren't about processor speed. Ask instead how many independent displays it can drive, whether it accepts one or two graphics cards, whether it supports at least 16 GB of RAM, whether it has an SSD, and whether it has stable Ethernet.

A secondhand six-core Intel i5 from several generations back already handles terminals, editor UI, and browser previews without strain. The harder problem is driving four or more independent displays, since most integrated graphics chips top out at two or three monitors and laptops are often more restrictive still. Docks and USB adapters can extend that, but they add compression, extra cables, and their own reliability problems. A desktop with a dedicated multi-output GPU sidesteps all of it.

The $25 Four-Monitor Graphics Card

The NVIDIA Quadro P620 is a professional workstation card, not a gaming card, and its display setup is unusually well suited to this use case:

• Four Mini DisplayPort connectors
• Four simultaneous displays
• Low-profile, single-slot design
• Maximum power draw around 40W
• No separate PCIe power connector

NVIDIA's own specs confirm the four Mini DisplayPort outputs, the single-slot form factor, and the 40W ceiling. I found secondhand units for around €25, which puts the card well below the price of most docking stations or multi-monitor USB adapter setups, and for a machine whose job is displaying terminals and editor windows rather than rendering games, that's plenty of headroom.

One warning: confirm you're buying a P620 and not the older K620. The K620 ships with just one DisplayPort and one DVI output, so it won't get you anywhere near four monitors.

Running Two Graphics Cards

Two P620 cards work independently in the same machine, with no SLI bridge, no NVLink, and no cable connecting them. The first card drives monitors one through four, the second drives five through eight, and Ubuntu presents all of them as a single extended desktop.

For this workload the second PCIe slot doesn't need much bandwidth, so even a slot with fewer lanes works fine for rendering desktop applications. Two secondhand P620 cards can give you eight monitor outputs for around €50 in GPU cost, provided the host machine has two usable PCIe slots, room for two single-slot cards, matching brackets, sufficient power headroom, and adequate airflow around both cards. Both cards run on the same NVIDIA driver.

This route is often easier to pull off than hunting for a rare six-output card, since four-output cards like the P620 are common on the secondhand market.

Choosing the Host Computer

Check what you already own before buying anything. An older business desktop is often enough:

• Dell OptiPlex
• HP EliteDesk
• Lenovo ThinkCentre
• A used custom-built tower
• Older office workstations

The CPU can be modest. A fourth-generation Intel i5 will do the job, and something like an eighth-generation i5-8500 gives you more local headroom than you'll use.

16 GB of RAM is the target. Eight gigabytes technically works, but five Cursor windows plus Ubuntu plus a browser will already push against that ceiling. DDR4 is cheap now, so bumping an 8 GB office PC to 16 GB usually costs very little.

An SSD matters even though your repositories live remotely, because the local machine still writes application data, browser cache, editor state, logs, and swap. A 250 GB SSD is plenty, since Docker data and large repos stay on the server.

PCIe slots determine your monitor ceiling. One P620 covers four monitors; two cover eight, assuming the board and case can physically accept them. A second full-length slot doesn't need to run at x16, since physical fit matters more than bandwidth here.

Case size rules cards in or out. Towers and small-form-factor cases generally accept graphics cards; Mini, Micro, and Tiny form factors usually don't have standard PCIe slots at all. Small-form-factor machines need low-profile brackets, towers need full-height brackets, and secondhand cards sometimes ship with only one bracket type, so check before buying.

Power supply headroom should cover roughly 40W per card, so two cards add about 80W to the system's peak draw. A standard tower PSU handles that without issue, though compact office machines running 180W or 200W proprietary supplies are worth checking. The P620 needs no separate GPU power cable, which makes it drop into office desktops without a PSU upgrade.

Example Build

Going to six or eight monitors just means a board with two usable PCIe slots, a second P620, and a few more Mini DisplayPort cables. The CPU stays the same.

Monitor Cables

The P620 outputs Mini DisplayPort, so the cleanest path is a direct Mini DisplayPort to DisplayPort cable rather than an adapter chain. Each adapter you add is another point where resolution or refresh rate can misbehave, and passive Mini DisplayPort to HDMI cables in particular carry their own resolution limits.

Before ordering cables, check your monitor's input type, the resolution and refresh rate you want, whether the cable actually supports that combination, and whether you need an active adapter. For coding work, 60Hz is enough. Higher refresh rates make scrolling feel smoother but add nothing essential to this setup.

Setting Up the Local Client

Ubuntu is a good fit here because the local machine doesn't need a large software ecosystem. It only needs NVIDIA drivers, your editor, OpenSSH, a browser, a password manager, and whatever display arrangement tool you prefer.

Ubuntu 26.04 LTS asks for a 2GHz dual-core CPU, 6 GB of RAM, and 25 GB of storage for a comfortable install, and a 16 GB machine will run the standard desktop without trouble. The release also includes NVIDIA-related improvements aimed at smoother GNOME performance with NVIDIA drivers.

Keep the local install lean. Skip local databases, container runtimes, and language toolchains unless you genuinely need them there, since every local dependency you add pulls the client back toward doing work it shouldn't be doing.

Configuring the SSH Connection

Create a host alias in ~/.ssh/config:

# File: ~/.ssh/config
Host development
    HostName your-server.example.com
    User developer
    IdentityFile ~/.ssh/id_ed25519
    ServerAliveInterval 30
    ServerAliveCountMax 3

Connect with:

ssh development

This alias means the editor's Remote SSH connection picker just needs the name development, and you can open your project directory directly on the server from there.

In Cursor or VS Code, select the Remote SSH connection and open the project folder on the server. The remote folder behaves like a normal workspace, but every command you run in its integrated terminal executes on the remote machine. VS Code's Remote SSH documentation describes this as opening a remote folder while keeping the editor's usual features intact.

Accessing Website Previews

Say your dev server runs a Next.js app on port 3000:

pnpm dev

You don't need to expose that port publicly. Tunnel it through SSH instead:

ssh -L 3000:localhost:3000 development

Then open http://localhost:3000 in your local browser. Traffic runs through the SSH tunnel to the remote server, so nothing is exposed beyond your own connection.

For multiple projects, map each to its own local port:

ssh \
  -L 3001:localhost:3000 \
  -L 3002:localhost:3001 \
  -L 3003:localhost:3002 \
  development

Some Remote SSH implementations detect and forward dev server ports automatically, so check your editor's behavior before setting up manual tunnels for every project.

Security Considerations

Your remote server now holds your active development environments, so locking it down deserves real attention. Use SSH keys instead of passwords, disable direct root login, and run everything under a dedicated non-root user. Keep the OS patched, restrict exposed ports with a firewall, and back up repositories and persistent data on a schedule. Separate production credentials from development credentials, encrypt local storage in case the client machine is lost or stolen, and consider routing the connection through a VPN or private network.

The client itself shouldn't become a long-term home for copied credentials or environment files. One benefit of this architecture is that replacing the local machine is simple: install the editor, restore your SSH key securely, and reconnect. Nothing about your development environment needs rebuilding.

Network Latency Over Raw Bandwidth

Remote development doesn't require heavy download bandwidth, since the editor exchanges filesystem operations, terminal output, and extension messages rather than streaming video of a remote desktop. Latency and connection stability carry far more weight.

A wired Ethernet connection suits a fixed workstation well, and a stable fibre or cable line will make a nearby server feel close to local for everyday editing. Things get uncomfortable when the connection drops frequently, latency runs high, a repository operation floods the terminal with output, the server sits far away geographically, remote storage is slow, or the remote editor process gets overloaded. Picking a data centre in your own region, rather than the cheapest available, avoids most of this.

FAQ

Do I need a powerful CPU on the local machine? No. A secondhand six-core Intel i5 from several generations back handles terminals, editor rendering, and browser previews without strain, since the heavy computation runs on the remote server.

How much RAM does the local client actually need? 16 GB is the practical minimum for running several Cursor or VS Code windows alongside a browser and desktop environment. 8 GB works but leaves little headroom.

Can I use a gaming GPU instead of the P620? You can, but most gaming GPUs support two or three outputs and cost far more than a $25 workstation card built for exactly this display count.

Does the P620 need extra power cables? No. It draws a maximum of about 40W and pulls power directly from the PCIe slot, which is part of why it fits into office desktops without a PSU upgrade.

What if my internet connection is slow? Bandwidth matters less than latency and stability here. A modest connection with low latency to a nearby server will feel more responsive than a fast connection to a distant one.

Wrapping Up

Splitting your development environment across a lightweight local client and a capable remote VPS turns an old office desktop and a $25 graphics card into a genuine multi-monitor AI coding workstation. The Hetzner server handles repositories, builds, and containers, while the local machine's only job is rendering windows reliably across as many displays as you can attach to it. For anyone running several AI coding agents across multiple projects at once, that display space tends to matter more than another CPU upgrade ever would.

Let me know in the comments if you have questions, and subscribe for more practical development guides.

Thanks, Matija

I set this up for a client project that runs Payload CMS on Next.js across dev, staging, and production, with GitHub Actions building the Docker image and a Compose file handling runtime. The team had been passing .env files around in Slack before this, which is exactly the failure mode Infisical exists to prevent. What follows is the workflow that replaced it, including the two mistakes that cost me the most time: assuming --silent actually silenced the CLI, and pointing a CI runner at localhost:8085.

Why process injection instead of a .env file

A .env file sitting on disk is a file that can get committed, screenshotted, or copied into a support ticket. infisical run -- <command> skips that step by fetching secrets and setting them as environment variables directly on the child process. The values live in memory for that process only. Reach for infisical export --output-file when you genuinely need a local file, such as feeding a tool that only reads dotenv files, and treat that as the exception rather than the default.

Platform configuration

localhost:8085 is a developer-facing local forward. CI runners and containers cannot reach it because localhost always resolves to the current host. Server bootstrap files need the approved HTTPS Infisical hostname instead, which shows up later in the CI and runtime sections.

Security rules to follow from the start

A few habits prevent most of the incidents that happen with secrets tooling:

• Never commit .env, machine client secrets, access tokens, or exported values.
• Use a personal Infisical account for development, and separate read-only Universal Auth machine identities for staging CI, production CI, and production runtime.
• Keep development values out of staging and production; provision each environment independently.
• Redirect every secrets set and export command's output, because CLI 0.43.84 prints values even with --silent set.
• Skip shell tracing (set -x) anywhere near a secret command.
• Rotate a credential immediately if it appears in a terminal transcript, CI log, screenshot, ticket, or chat message.

1. Install the CLI

Pin the version for reproducibility across every machine that touches the project.

# Persistent installation
pnpm add --global @infisical/cli@0.43.84
infisical --version

Expected output:

infisical version 0.43.84

For a one-off run without a global install:

pnpm dlx @infisical/cli@0.43.84 --version

Swap infisical for pnpm dlx @infisical/cli@0.43.84 in any command below if you'd rather not install globally.

2. Authenticate

Start the local Infisical forward, then log in:

infisical login --domain=http://localhost:8085

This opens a browser callback. Complete it with your personal account. The CLI stores the session in its local credential vault and never writes the login token into the repository.

Confirm the session is active:

infisical login status --domain=http://localhost:8085

If the browser callback doesn't fire on its own, open the URL the CLI prints in the terminal.

3. Link the repository

A checked-in .infisical.json links the repo to the right project and defaults to dev. To recreate that linkage from scratch:

infisical init --domain=http://localhost:8085

Pick your organization, then your project, from the prompts. The resulting file holds project metadata only:

{
  "workspaceId": "00000000-0000-0000-0000-000000000000",
  "defaultEnvironment": "dev",
  "gitBranchToEnvironmentMapping": null
}

4. Upload an existing .env to dev

Check which keys you're about to upload before you run anything, since this command shows names only:

awk -F= '/^[A-Za-z_][A-Za-z0-9_]*=/{print $1}' .env | sort

Then upload every valid entry as a shared secret at the root path:

infisical secrets set \
  --domain=http://localhost:8085 \
  --env=dev \
  --path=/ \
  --type=shared \
  --file=.env \
  --silent \
  >/dev/null

This creates any missing keys and updates the ones that already exist, including empty values. Comment lines in the source file are skipped automatically. The output redirect matters here: without it, the terminal fills with a table of your secret values despite --silent being set. Keep dev, staging, and production values independent; don't push the same .env into more than one environment.

5. Verify an upload without exposing values

Injecting secrets into a short Node script and checking for presence is safer than printing them:

infisical run \
  --domain=http://localhost:8085 \
  --env=dev \
  --silent \
  -- node -e '
    const expected = [
      "DATABASE_URL",
      "NEXT_PUBLIC_SERVER_URL",
      "PAYLOAD_SECRET",
      "DEFAULT_SITE_SLUG",
      "SITE_HOST_MAP",
      "INTEGRATIONS_MODE",
    ]
    const missing = expected.filter((key) => !process.env[key])
    console.log(JSON.stringify({
      injection: "ok",
      expected: expected.length,
      present: expected.length - missing.length,
      missing,
    }))
    process.exit(missing.length ? 2 : 0)
  '

Steer clear of printenv, env, infisical secrets --output=json, or piping an export to standard output for this check. Each of those prints the actual values.

6. Run the application with process-only injection

For day-to-day development:

infisical run \
  --domain=http://localhost:8085 \
  --env=dev \
  -- pnpm dev

If your package.json wraps this in a script (for example pnpm dev:infisical), use that instead. The same pattern works for any command that needs environment access:

# Seed development data
infisical run \
  --domain=http://localhost:8085 \
  --env=dev \
  -- pnpm db:seed

# Run catalog validation with the same environment
infisical run \
  --domain=http://localhost:8085 \
  --env=dev \
  -- pnpm catalog:validate

The child process reads process.env normally. infisical run never touches .env on disk.

7. Pull secrets into a local .env when you actually need one

infisical export \
  --domain=http://localhost:8085 \
  --env=dev \
  --path=/ \
  --format=dotenv \
  --output-file=.env \
  --silent \
  >/dev/null

chmod 600 .env

Confirm the keys and file permissions without displaying values:

awk -F= '/^[A-Za-z_][A-Za-z0-9_]*=/{print $1}' .env | sort
stat -c 'mode=%a' .env   # macOS: stat -f 'mode=%Lp' .env

You're looking for mode=600. Your .gitignore should already exclude .env* except .env.example, but check before every commit anyway:

git status --short
git check-ignore -v .env

8. Create or update individual secrets

For a quick one-off during development:

infisical secrets set \
  EXAMPLE_KEY=example-value \
  --domain=http://localhost:8085 \
  --env=dev \
  --path=/ \
  --type=shared \
  >/dev/null

For anything sensitive, put the value in a permission-restricted temporary file rather than your shell history, or use the Infisical dashboard directly:

chmod 600 /path/to/update.env

infisical secrets set \
  --domain=http://localhost:8085 \
  --env=dev \
  --path=/ \
  --type=shared \
  --file=/path/to/update.env \
  --silent \
  >/dev/null

9. Read a single secret safely

Printing a secret value should be rare enough that it feels deliberate every time:

infisical secrets get SECRET_NAME \
  --domain=http://localhost:8085 \
  --env=dev \
  --path=/

For a presence check instead, inject it into a process:

infisical run \
  --domain=http://localhost:8085 \
  --env=dev \
  --silent \
  -- node -e '
    const key = "SECRET_NAME"
    console.log(process.env[key] ? `${key}: present` : `${key}: missing`)
    process.exit(process.env[key] ? 0 : 2)
  '

10. Delete a secret

Deletion touches shared external state, so double-check the environment, path, and key first:

infisical secrets delete SECRET_NAME \
  --domain=http://localhost:8085 \
  --env=dev \
  --path=/

Restart anything that depends on the deleted secret and confirm it comes back healthy.

11. Secret folders

Most projects keep everything at the root path (/). Folders become useful once a specific integration needs isolation from the rest of the secrets.

infisical secrets folders get \
  --domain=http://localhost:8085 \
  --env=dev \
  --path=/ \
  --output=json

Whatever --path you use, keep it consistent across secrets set, run, and export for that integration.

12. Required application keys

For a Next.js and Payload CMS deployment, staging and production validation typically checks:

DATABASE_URL
DATABASE_UNPOOLED_URL
SERVER_URL
NEXT_PUBLIC_SERVER_URL
PAYLOAD_SECRET
CRON_SECRET
S3_BUCKET
S3_ENDPOINT

The application layer also tends to use:

DEFAULT_SITE_SLUG
SITE_HOST_MAP
INTEGRATIONS_MODE
CACHE_REDIS_URL
CACHE_REDIS_PREFIX
CACHE_REDIS_MAX_ENTRY_BYTES

If your project carries DATABASE_URL_DIRECT from an older setup, rename it to DATABASE_UNPOOLED_URL. Migration scripts written against the newer name won't find the old one.

13. Validate staging or production keys

Run this from an authenticated developer machine, never from a CI runner pointed at localhost:

infisical run \
  --domain=http://localhost:8085 \
  --env=staging \
  -- bash deployment-templates/validate-infisical-env.sh staging runtime

infisical run \
  --domain=http://localhost:8085 \
  --env=prod \
  -- bash deployment-templates/validate-infisical-env.sh production runtime

A good validator reports missing key names only and flags obviously invalid database hosts, without ever printing a value.

14. Machine identities for CI and runtime

Copying your personal login token onto a server defeats the point of having separate access levels. Create three Universal Auth identities instead:

1. Staging CI/build/migration — read-only access to staging, path /.
2. Production CI/build/migration — read-only access to prod, path /.
3. Production runtime — read-only access to prod, path /.

Each identity gets its own bootstrap file on the target host:

/etc/infisical/website-platform-staging.env
/etc/infisical/website-platform-production.env

INFISICAL_API_URL=https://secrets.example.com
INFISICAL_PROJECT_ID=00000000-0000-0000-0000-000000000000
INFISICAL_ENV=staging
INFISICAL_SECRET_PATH=/
INFISICAL_UNIVERSAL_AUTH_CLIENT_ID=replace-me
INFISICAL_UNIVERSAL_AUTH_CLIENT_SECRET=replace-me
INFISICAL_DISABLE_UPDATE_CHECK=true

Lock down permissions on both files, and never commit a completed one:

sudo chown root:<runner-group> /etc/infisical/website-platform-staging.env
sudo chown root:<runner-group> /etc/infisical/website-platform-production.env
sudo chmod 640 /etc/infisical/website-platform-staging.env
sudo chmod 640 /etc/infisical/website-platform-production.env

Production runtime can go tighter still, with root:root ownership and mode 600.

15. Test a machine identity

From the target host:

INFISICAL_BOOTSTRAP_FILE=/etc/infisical/website-platform-staging.env \
  sh scripts/infisical-exec.sh \
  bash deployment-templates/validate-infisical-env.sh staging runtime

A wrapper script like this one reads the root-protected bootstrap file, exchanges the Universal Auth client credential for a short-lived token, strips the long-lived credential out of the child environment, runs infisical run, and hands the application process its values.

16. Build-time injection with Docker BuildKit

CI (GitHub Actions or Bitbucket Pipelines) runs BuildKit inside the same exec wrapper. Infisical typically injects three build-time values:

PAYLOAD_SECRET
DATABASE_URL
NEXT_PUBLIC_SERVER_URL

BuildKit receives each one through --secret id=...,env=..., and the Dockerfile mounts them under /run/secrets/ only for the duration of pnpm build. They never become build arguments and never land in an image layer. If you're used to --build-arg, resist the pull toward it here:

--build-arg PAYLOAD_SECRET=...

Build arguments get baked into image metadata, which is the opposite of what a secret mount is for.

17. Runtime injection

Staging and production Compose files mount a single bootstrap credential:

/run/secrets/infisical_bootstrap

The image entrypoint authenticates to Infisical, fetches the target environment, drops privileges to a non-root user, and starts the server with the fetched values already in process.env. After changing any runtime secret, restart the container so it picks up the new value:

docker compose restart app

18. Rotating a credential

Application credentials (database, external API keys)

1. Rotate the credential at its source.
2. Update the corresponding Infisical environment.
3. Restart or redeploy the application.
4. Check /api/health.
5. Revoke the old credential once the new one is confirmed working.

Updating Infisical without rotating the credential at its source leaves the old value live wherever it was issued.

Universal Auth client secrets

1. Generate a new client secret for that exact machine identity.
2. Update the matching /etc/infisical/*.env bootstrap file.
3. Restart the workload or rerun the validation wrapper.
4. Confirm injection succeeded and the application is healthy.
5. Revoke the old client secret.

Comparing the three secret-delivery paths

Troubleshooting

"Environment with slug 'demo' not found" Use one of the environments actually configured for the project: dev, staging, or prod.

"Injecting 0 Infisical secrets" The project, environment, and path all resolve, but nothing is accessible from them. Check the project linkage, the environment slug, the path (usually /), that secrets exist there, and that your account or machine identity has read access.

"Folder with path '/' ... was not found" Either the environment slug is wrong, or that environment has never had a root secret or folder initialized. Recheck both.

"File does not exist" --file=.env needs a local file to already exist. Pull it fresh with infisical export --output-file=.env or recreate it from an approved source.

Login works, but commands hit Infisical Cloud instead of your self-hosted instance Pass --domain=http://localhost:8085 on every command, or set it once for scripts:

export INFISICAL_API_URL=http://localhost:8085

The local URL works, but CI or a container can't connect localhost always points at the current process's own host. CI runners and containers need the actual HTTPS Infisical hostname reachable from where they run, configured in the bootstrap file.

The CLI prints secret values despite --silent Redirect the command's output:

infisical secrets set ... --file=.env --silent >/dev/null
infisical export ... --output-file=.env --silent >/dev/null

If a value already made it into a saved log somewhere, rotate it.

Command quick reference

# Login
infisical login --domain=http://localhost:8085

# Link repository
infisical init --domain=http://localhost:8085

# Upload .env to dev
infisical secrets set \
  --domain=http://localhost:8085 \
  --env=dev \
  --path=/ \
  --type=shared \
  --file=.env \
  --silent >/dev/null

# Run without writing .env
infisical run \
  --domain=http://localhost:8085 \
  --env=dev \
  -- pnpm dev

# Pull to a local file
infisical export \
  --domain=http://localhost:8085 \
  --env=dev \
  --path=/ \
  --format=dotenv \
  --output-file=.env \
  --silent >/dev/null
chmod 600 .env

# Validate staging
infisical run \
  --domain=http://localhost:8085 \
  --env=staging \
  -- bash deployment-templates/validate-infisical-env.sh staging runtime

FAQ

Does --silent actually hide secret values in Infisical CLI 0.43.84? No, not for secrets set. That version prints a result table containing the values regardless of the flag. Redirect standard output to /dev/null on every upload or export command until you've confirmed a fix in a newer release.

Why does my CI runner fail to connect to http://localhost:8085? Because localhost resolves to the runner's own container, not your development machine. CI and production hosts need the real HTTPS Infisical hostname configured in their bootstrap files.

Should I use one Universal Auth identity for both staging and production? No. Provision a separate read-only identity for staging CI, production CI, and production runtime. If one leaks, the blast radius stays limited to a single environment.

What's the difference between infisical run and infisical export? infisical run injects secrets into a child process's memory and never writes them to disk. infisical export writes them into a real file, which is useful only when a tool genuinely requires a dotenv file to read from.

Can I pass a secret as a Docker build argument instead of a secret mount? You can, but you shouldn't. Build arguments get recorded in image metadata. A BuildKit --secret mount exposes the value only inside the build step and leaves nothing behind in the image.

Setting this up once, with the right environment separation and machine identities, removes the temptation to pass a .env file around informally later. Let me know in the comments if you run into a rougher edge with a different CLI version, and subscribe for more practical development guides.

Thanks, Matija

In the previous article, I covered why .env files stop being a sufficient secrets-management system once an application picks up multiple developers, deployment environments, servers, and external services. This one covers what replaces them. I wanted something that felt close to managing environment variables in Vercel, without being tied to Vercel, and that would work across local development, staging, production, Docker containers, background workers, and plain VPS deployments regardless of framework. Infisical is what I landed on, and this guide walks through the full setup.

What this guide covers

• Self-hosting Infisical on a dedicated VPS
• Putting it behind HTTPS
• Creating development, staging, and production environments
• Connecting a local project, whatever it's built with
• Giving staging and production servers separate machine identities
• Injecting secrets into a systemd service
• Injecting secrets into Docker containers
• Handling build-time variables correctly (using Next.js as the example)
• Backing up the Infisical database and encryption keys
• Rotating secrets without falling back to copied .env files

The end result looks like this regardless of what you're running:

Developer laptop
  └── Infisical CLI
        └── development secrets

Staging VPS
  └── staging machine identity
        └── staging secrets

Production VPS
  └── production machine identity
        └── production secrets

Infisical VPS
  ├── Infisical
  ├── PostgreSQL
  ├── Redis
  └── HTTPS reverse proxy

Your application keeps reading ordinary environment variables through whatever mechanism your language or framework already uses, process.env in Node.js being the obvious one. Infisical controls where those values are stored, who may retrieve them, and which environment each application receives. The application code itself doesn't need to know Infisical exists.

What this guide assumes

This guide assumes Ubuntu or Debian on the servers, Docker and Docker Compose on the Infisical VPS, a domain such as secrets.example.com, separate staging and production servers, and a small team or small-scale production deployment. The application examples use Next.js with Payload CMS and pnpm, since that's the stack I run most often, but nothing about Infisical itself is specific to that combination. Swap in a Django app, a Go service, a Rails app, or anything else that reads configuration from the environment, and the Infisical side of this guide stays the same.

Infisical's official Docker Compose template runs the application, PostgreSQL, and Redis on a single Docker host. Infisical documents this deployment model as suitable for development, testing, proofs of concept, and smaller deployments that don't require high availability, with a documented minimum of two CPU cores, 4 GB RAM, and 20 GB disk for the complete stack, and higher resources recommended beyond that.

For this guide, I'd use at least:

4 vCPU
8 GB RAM
50 GB SSD

A smaller server works fine for testing, but a secrets manager is infrastructure that every one of your applications may depend on during startup, so I'd rather give it comfortable headroom from the start. For a larger organization or a high-availability requirement, run Infisical against external PostgreSQL and Redis services or a more resilient orchestration setup.

The target architecture

The Infisical server should sit separately from your application servers, regardless of what those application servers run.

Internet
  │
  ▼
secrets.example.com
  │
  ▼
Nginx with TLS
  │
  ▼
Infisical container
  ├── PostgreSQL container
  └── Redis container

Application servers connect to the Infisical API over HTTPS:

Production VPS
  │
  ├── Client ID
  ├── Client Secret
  │
  ▼
Infisical Universal Auth
  │
  ▼
Short-lived access token
  │
  ▼
Production secrets
  │
  ▼
Application process

The application server never stores the database password, application secret, storage credentials, SMTP password, and every external API key in a local .env.production file. It stores one restricted bootstrap credential that lets it request the correct secrets from Infisical, and that's true whether the process at the bottom of that chain is Next.js, Payload, or something else entirely.

Step 1: Prepare the Infisical VPS

Start by creating a dedicated installation directory:

sudo mkdir -p /opt/infisical
sudo chown "$USER":"$USER" /opt/infisical
cd /opt/infisical

Verify that Docker and Docker Compose are installed:

docker --version
docker compose version

Download the official Docker Compose template and example configuration:

curl -fsSL \
  -o docker-compose.prod.yml \
  https://raw.githubusercontent.com/Infisical/infisical/main/docker-compose.prod.yml

curl -fsSL \
  -o .env \
  https://raw.githubusercontent.com/Infisical/infisical/main/.env.example

Protect the configuration file:

chmod 600 .env

The downloaded .env contains example credentials that must not be used in production. Infisical explicitly marks the example encryption and authentication values as unsafe for production use.

Step 2: Pin the Infisical image

The current official Compose template contains:

image: infisical/infisical:latest

It also includes a comment telling operators to pin the image to a specific tag. Open the file:

nano docker-compose.prod.yml

Change:

image: infisical/infisical:latest

To a specific version that you've reviewed:

image: infisical/infisical:<PINNED_VERSION>

A floating latest tag has no place in infrastructure that stores the credentials for every other application you run. The same principle applies to PostgreSQL and Redis: pin versions, test upgrades in a non-production environment, back up the database, and upgrade deliberately.

Step 3: Bind Infisical to localhost

The official template publishes the backend directly on port 80:

ports:
  - 80:8080

I prefer to expose Infisical only through the reverse proxy. Change the backend port mapping to:

services:
  backend:
    ports:
      - "127.0.0.1:8080:8080"

The service is now reachable from the VPS itself at http://127.0.0.1:8080 and stays off the public network interface. Nginx will terminate TLS and forward requests to this local port.

Step 4: Generate the platform secrets

Infisical requires an encryption key and an authentication secret. Generate the encryption key:

openssl rand -hex 16

Generate the authentication secret:

openssl rand -base64 32

Generate a PostgreSQL password using hexadecimal characters so it can safely appear inside a connection URI:

openssl rand -hex 24

Infisical currently documents ENCRYPTION_KEY as a random 16-byte hexadecimal string and AUTH_SECRET as a random 32-byte Base64 string. Open the configuration:

nano /opt/infisical/.env

Replace the sample values with your generated values:

# File: /opt/infisical/.env
ENCRYPTION_KEY=<GENERATED_HEX_ENCRYPTION_KEY>
AUTH_SECRET=<GENERATED_BASE64_AUTH_SECRET>

POSTGRES_USER=infisical
POSTGRES_PASSWORD=<GENERATED_POSTGRES_PASSWORD>
POSTGRES_DB=infisical

DB_CONNECTION_URI=postgresql://infisical:<GENERATED_POSTGRES_PASSWORD>@db:5432/infisical
REDIS_URL=redis://redis:6379

SITE_URL=https://secrets.example.com

TELEMETRY_ENABLED=false

Leave the rest of the optional integration settings empty unless you need them. The platform requires an absolute SITE_URL, including the protocol. PostgreSQL is the persistent data layer here, and Redis handles caching and background work.

Check the permissions again:

chmod 600 /opt/infisical/.env

Step 5: Start Infisical

Start the stack:

cd /opt/infisical

docker compose \
  -f docker-compose.prod.yml \
  up -d

Check the containers:

docker compose \
  -f docker-compose.prod.yml \
  ps

Inspect the logs if a container isn't healthy:

docker compose \
  -f docker-compose.prod.yml \
  logs --tail=100

Test the local API:

curl -fsS http://127.0.0.1:8080/api/status

You should get a successful response from the Infisical backend.

Step 6: Configure Nginx and HTTPS

Install Nginx and Certbot:

sudo apt-get update
sudo apt-get install -y nginx certbot python3-certbot-nginx

Create the Nginx virtual host:

sudo nano /etc/nginx/sites-available/secrets.example.com

Add:

# File: /etc/nginx/sites-available/secrets.example.com
server {
    listen 80;
    listen [::]:80;

    server_name secrets.example.com;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_read_timeout 300;
        proxy_send_timeout 300;
    }
}

Enable the site:

sudo ln -s \
  /etc/nginx/sites-available/secrets.example.com \
  /etc/nginx/sites-enabled/secrets.example.com

Test the configuration and reload Nginx:

sudo nginx -t
sudo systemctl reload nginx

Make sure the DNS record points to the Infisical VPS:

secrets.example.com    A    <INFISICAL_VPS_IP>

Then request the certificate:

sudo certbot \
  --nginx \
  -d secrets.example.com

Verify the result:

curl -fsS https://secrets.example.com/api/status

Running the public Infisical interface over plain HTTP isn't an option here. Infisical uses secure cookies for authenticated sessions, and its own documentation recommends SSL for self-hosted deployments.

Step 7: Create the administrator account

Open https://secrets.example.com and create your account as soon as the installation becomes reachable. In the Docker Compose installation flow, the first registered user becomes the instance administrator, so this step needs to happen before the instance is shared or widely exposed. For a stricter initial setup, temporarily restrict port 443 to your IP address while creating the first account.

After creating the administrator, configure SMTP for password resets and invitations, invite the developers who need access, enable multi-factor authentication, review whether public sign-up should stay available, and confirm that only the reverse proxy can reach the backend port.

Step 8: Configure SMTP

Infisical uses email for invitations, password resets, and notifications. Add the SMTP configuration to /opt/infisical/.env:

# File: /opt/infisical/.env
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USERNAME=<SMTP_USERNAME>
SMTP_PASSWORD=<SMTP_PASSWORD>
SMTP_FROM_ADDRESS=secrets@example.com
SMTP_FROM_NAME=Infisical

Restart the backend:

cd /opt/infisical

docker compose \
  -f docker-compose.prod.yml \
  restart backend

Test the password-reset flow before relying on the instance for production infrastructure.

Step 9: Create the application project

In Infisical, create a Secrets Management project:

Project name: My Application

Configure three environments:

Development    dev
Staging        staging
Production     prod

Infisical projects organize secrets into environments, folders, and individual values, and the same key can exist in each environment with a different value. Using a Next.js and Payload stack as an example:

Keep the key names consistent across environments regardless of what framework is consuming them. A starting set for a Payload application might look like:

# File: Infisical → My Application → dev/staging/prod
NODE_ENV=production
APP_ENV=
SERVER_URL=

DATABASE_URL=
DATABASE_URL_UNPOOLED=

PAYLOAD_SECRET=

S3_ENDPOINT=
S3_REGION=
S3_BUCKET=
S3_ACCESS_KEY_ID=
S3_SECRET_ACCESS_KEY=

REDIS_URL=

SMTP_HOST=
SMTP_PORT=
SMTP_USERNAME=
SMTP_PASSWORD=

BREVO_API_KEY=

CRON_SECRET=
PREVIEW_SECRET=

A different stack would list different keys, but the structure, one project, three environments, consistent naming, stays the same. You can import an existing .env file through the Infisical interface, but review every value first and make sure it lands in the correct environment.

Step 10: Keep .env.example in Git

Infisical becomes the source of truth for the actual secret values, but the repository should still document which variables the application expects. Create:

# File: .env.example

NODE_ENV=
APP_ENV=
SERVER_URL=

DATABASE_URL=
DATABASE_URL_UNPOOLED=

PAYLOAD_SECRET=

S3_ENDPOINT=
S3_REGION=
S3_BUCKET=
S3_ACCESS_KEY_ID=
S3_SECRET_ACCESS_KEY=

REDIS_URL=

SMTP_HOST=
SMTP_PORT=
SMTP_USERNAME=
SMTP_PASSWORD=

BREVO_API_KEY=

CRON_SECRET=
PREVIEW_SECRET=

This documents the configuration contract without containing credentials, and it's worth keeping around no matter which application reads it.

Step 11: Install the Infisical CLI locally

On macOS:

brew install infisical/get-cli/infisical

On Debian or Ubuntu:

curl -1sLf \
  "https://artifacts-cli.infisical.com/setup.deb.sh" \
  | sudo -E bash

sudo apt-get update
sudo apt-get install -y infisical

Infisical also distributes the CLI through NPM:

npm install -g @infisical/cli

For a production server, pin the CLI version instead of silently installing an arbitrary future release. Infisical explicitly recommends version pinning for production environments.

Step 12: Connect your local project

Navigate to the application directory, whatever it contains:

cd /path/to/my-application

Log in:

infisical login

The current CLI can interactively select a self-hosted instance, or you can define your domain explicitly:

export INFISICAL_DOMAIN="https://secrets.example.com"

Initialize the project:

infisical init

Select the Infisical project when prompted. This creates .infisical.json. Update it to include the self-hosted domain and default environment:

{
  "workspaceId": "<INFISICAL_PROJECT_ID>",
  "defaultEnvironment": "dev",
  "domain": "https://secrets.example.com"
}

Infisical's project configuration file stores the project reference, default environment, and optional self-hosted domain. The documentation notes that this file is usually committed to the repository, so review the configured domain carefully before committing it. The file itself never contains the secret values.

Step 13: Run your application locally through Infisical

Your application code doesn't need to import an Infisical SDK. For a Next.js and Payload project, Payload keeps reading its configuration from process.env exactly as before:

// File: src/payload.config.ts

import { buildConfig } from 'payload'
import { postgresAdapter } from '@payloadcms/db-postgres'

export default buildConfig({
  secret: process.env.PAYLOAD_SECRET ?? '',
  serverURL: process.env.SERVER_URL,
  db: postgresAdapter({
    pool: {
      connectionString: process.env.DATABASE_URL,
    },
  }),
})

Payload officially supports reading environment variables directly from process.env inside its configuration, and the same is true for essentially any framework that reads configuration from the process environment. Start the application through Infisical:

infisical run --env=dev -- pnpm dev

Infisical retrieves the development values and injects them into the pnpm dev process. Swap pnpm dev for whatever your stack uses to start locally, python manage.py runserver, go run ., rails server, and the pattern holds. You can add a convenience script:

{
  "scripts": {
    "dev": "next dev",
    "dev:secrets": "infisical run --env=dev -- pnpm dev",
    "build": "next build",
    "start": "next start"
  }
}

Run:

pnpm dev:secrets

Verify that a value exists without printing the value itself:

infisical run --env=dev -- \
  node -e "console.log('DATABASE_URL available:', Boolean(process.env.DATABASE_URL))"

Expected output:

DATABASE_URL available: true

Step 14: Handle build-time variables (the Next.js case)

Runtime injection through infisical run covers most frameworks completely, but a few tools also embed configuration into a build artifact rather than reading it purely at runtime. Next.js is the clearest example, so it's worth walking through even in an otherwise stack-agnostic setup.

Server-side values like these should never be prefixed with NEXT_PUBLIC_:

DATABASE_URL
PAYLOAD_SECRET
S3_SECRET_ACCESS_KEY
SMTP_PASSWORD
BREVO_API_KEY

A value prefixed with NEXT_PUBLIC_ is meant for browser access:

NEXT_PUBLIC_SITE_URL
NEXT_PUBLIC_ANALYTICS_ID
NEXT_PUBLIC_MAPBOX_TOKEN

Next.js replaces NEXT_PUBLIC_ references during next build, embedding the values directly into the browser bundle, where they stay fixed after the build completes. If your framework has an equivalent build-time embedding step, check its documentation for the same distinction before wiring up Infisical, since the fix is always the same: run the build itself through infisical run so the values are present at build time, not just at process startup. Never solve a missing browser variable by marking a secret public.

Step 15: Create a production machine identity

Developers should log in as themselves. Servers, regardless of what they run, shouldn't use a developer account. For production, create a machine identity:

Organization Settings
  → Access Control
  → Identities
  → Create identity

Name it clearly:

my-application-production

Configure Universal Auth, which gives the machine identity a Client ID and Client Secret. The server exchanges these for a short-lived access token. Next, add the identity to the project:

Project Settings
  → Access Control
  → Machine Identities
  → Add identity

Grant it read-only access to:

Project: My Application
Environment: Production
Path: /

The production identity should never read development, staging, or unrelated client projects. Create a separate identity for staging:

my-application-staging

Give it access only to the staging environment. The identities stay separate because their permission sets are different, and that separation matters regardless of what's actually running on either server.

Step 16: Store the bootstrap credential on the VPS

The production server still needs an initial credential that lets it authenticate to Infisical. Create a dedicated application user if one doesn't already exist:

sudo adduser --system \
  --group \
  --home /srv/my-application \
  my-application

Create the configuration directory:

sudo install \
  -d \
  -m 750 \
  -o root \
  -g my-application \
  /etc/my-application

Create the bootstrap file:

sudo nano /etc/my-application/infisical.env

Add:

# File: /etc/my-application/infisical.env
INFISICAL_DOMAIN=https://secrets.example.com
INFISICAL_PROJECT_ID=<PROJECT_ID>
INFISICAL_ENV=prod

INFISICAL_CLIENT_ID=<PRODUCTION_CLIENT_ID>
INFISICAL_CLIENT_SECRET=<PRODUCTION_CLIENT_SECRET>

INFISICAL_DISABLE_UPDATE_CHECK=true

Protect it:

sudo chown root:my-application \
  /etc/my-application/infisical.env

sudo chmod 640 \
  /etc/my-application/infisical.env

This file is the remaining secret-zero credential. It's still sensitive, but it's far narrower than a complete production .env file: it can be revoked independently, and its permissions can be limited to one project and one environment, no matter what application ends up consuming the secrets it unlocks.

Step 17: Create a reusable Infisical execution wrapper

Create:

sudo nano /usr/local/bin/my-application-infisical

Add:

#!/usr/bin/env bash
# File: /usr/local/bin/my-application-infisical

set -euo pipefail

set -a
source /etc/my-application/infisical.env
set +a

export PATH="/usr/local/bin:/usr/bin:/bin"

export INFISICAL_TOKEN="$(
  infisical login \
    --method=universal-auth \
    --client-id="$INFISICAL_CLIENT_ID" \
    --client-secret="$INFISICAL_CLIENT_SECRET" \
    --silent \
    --plain
)"

exec infisical run \
  --projectId="$INFISICAL_PROJECT_ID" \
  --env="$INFISICAL_ENV" \
  --path="/" \
  -- "$@"

Make it executable:

sudo chmod 750 \
  /usr/local/bin/my-application-infisical

sudo chown root:my-application \
  /usr/local/bin/my-application-infisical

The wrapper does two things: it exchanges the Universal Auth credentials for a short-lived access token, then starts whatever command you hand it with the correct secrets injected. Infisical's CLI requires --projectId when authenticating through a machine identity, and it selects the environment and path through --env and --path. Because the wrapper just wraps a command, it works identically whether that command is pnpm start, gunicorn, or a compiled Go binary.

Test it:

sudo -u my-application \
  /usr/local/bin/my-application-infisical \
  node -e "console.log(Boolean(process.env.PAYLOAD_SECRET))"

Expected output:

true

Step 18: Build and migrate with production secrets

Some frameworks, Next.js and Payload among them, need environment variables present while evaluating configuration during the build or a migration step, not just at process startup. Run the build through the wrapper:

cd /srv/my-application/current

sudo -u my-application \
  /usr/local/bin/my-application-infisical \
  pnpm build

Run Payload migrations through the same wrapper:

cd /srv/my-application/current

sudo -u my-application \
  /usr/local/bin/my-application-infisical \
  pnpm payload migrate

The migration now receives the production database connection from Infisical rather than from a local file. Run migrations before restarting the production application, and confirm a recent database backup exists first.

Step 19: Run the application with systemd

Create the service:

sudo nano /etc/systemd/system/my-application.service

Add:

# File: /etc/systemd/system/my-application.service
[Unit]
Description=My application
After=network-online.target
Wants=network-online.target

[Service]
Type=simple

User=my-application
Group=my-application

WorkingDirectory=/srv/my-application/current

ExecStart=/usr/local/bin/my-application-infisical pnpm start

Restart=on-failure
RestartSec=5

Environment=NODE_ENV=production
Environment=PATH=/usr/local/bin:/usr/bin:/bin

NoNewPrivileges=true
PrivateTmp=true
ProtectHome=true
ProtectSystem=full

[Install]
WantedBy=multi-user.target

Swap pnpm start in ExecStart for whatever command actually starts your application. Reload systemd, then enable and start it:

sudo systemctl daemon-reload
sudo systemctl enable --now my-application

Check the status and follow the logs:

sudo systemctl status my-application
sudo journalctl -u my-application -f

The startup flow is now the same regardless of stack: systemd calls the execution wrapper, which logs in through Universal Auth, gets a short-lived access token, runs infisical run, and finally starts your application.

Step 20: Apply a changed secret

Suppose you replace BREVO_API_KEY. Update the value in the production environment inside Infisical. The currently running process will still have the old value in memory, since environment variables don't update inside an already running process. Restart the service:

sudo systemctl restart my-application

Infisical supports a --watch option that restarts a command automatically when secrets change, but its documentation recommends that feature for development rather than production. I prefer explicit production restarts tied to a reviewed configuration change, and that preference holds regardless of what's running behind the wrapper.

Step 21: Use Infisical with Docker

For a Docker deployment, install the Infisical CLI inside the application image. For an Alpine-based image:

# File: Dockerfile

RUN apk add --no-cache bash curl

RUN curl -1sLf \
  "https://artifacts-cli.infisical.com/setup.apk.sh" \
  | sh

RUN apk add --no-cache infisical

Create an entrypoint:

# File: docker/infisical-entrypoint.sh

#!/usr/bin/env bash

set -euo pipefail

export INFISICAL_TOKEN="$(
  infisical login \
    --method=universal-auth \
    --client-id="$INFISICAL_CLIENT_ID" \
    --client-secret="$INFISICAL_CLIENT_SECRET" \
    --silent \
    --plain
)"

exec infisical run \
  --projectId="$INFISICAL_PROJECT_ID" \
  --env="$INFISICAL_ENV" \
  --path="${INFISICAL_PATH:-/}" \
  -- "$@"

Copy it into the image:

# File: Dockerfile

COPY docker/infisical-entrypoint.sh \
  /usr/local/bin/infisical-entrypoint

RUN chmod +x \
  /usr/local/bin/infisical-entrypoint

ENTRYPOINT ["/usr/local/bin/infisical-entrypoint"]

CMD ["pnpm", "start"]

The application image still starts its normal command; the entrypoint adds the authentication and secret-injection step in front of it. Infisical's Docker integration follows this same general pattern for any base image: install the CLI in the container and use infisical run as the wrapper around whatever the container was already going to run.

Step 22: Configure Docker Compose

Store the bootstrap credentials on the host:

sudo mkdir -p /etc/my-application

sudo nano \
  /etc/my-application/infisical.env

Add:

# File: /etc/my-application/infisical.env
INFISICAL_DOMAIN=https://secrets.example.com
INFISICAL_PROJECT_ID=<PROJECT_ID>
INFISICAL_ENV=prod
INFISICAL_CLIENT_ID=<CLIENT_ID>
INFISICAL_CLIENT_SECRET=<CLIENT_SECRET>

Protect the file:

sudo chmod 600 \
  /etc/my-application/infisical.env

The Compose service can use it:

# File: docker-compose.production.yml

services:
  app:
    image: my-application:<VERSION>
    restart: unless-stopped

    env_file:
      - /etc/my-application/infisical.env

    environment:
      NODE_ENV: production
      INFISICAL_DISABLE_UPDATE_CHECK: "true"

    ports:
      - "127.0.0.1:3000:3000"

Start it:

docker compose \
  -f docker-compose.production.yml \
  up -d

Check the logs:

docker compose \
  -f docker-compose.production.yml \
  logs --tail=100 app

The container receives only the bootstrap configuration through the host file, and the actual application secrets get retrieved when the container starts. A user with unrestricted access to the Docker daemon effectively has root-level control over every container and its configuration, so access to Docker itself needs to stay restricted regardless of which secrets manager sits behind it.

Step 23: Handle Docker build-time values

Runtime injection doesn't automatically cover build-time variables. This matters most for anything like Next.js's NEXT_PUBLIC_* values, which get embedded during the build step rather than read at container startup.

When building the image, provide the Infisical access token as a BuildKit secret rather than a normal Docker build argument. Authenticate on the build machine:

export INFISICAL_DOMAIN="https://secrets.example.com"

export INFISICAL_TOKEN="$(
  infisical login \
    --method=universal-auth \
    --client-id="$INFISICAL_CLIENT_ID" \
    --client-secret="$INFISICAL_CLIENT_SECRET" \
    --silent \
    --plain
)"

Build:

DOCKER_BUILDKIT=1 docker build \
  --secret id=infisical_token,env=INFISICAL_TOKEN \
  --build-arg INFISICAL_PROJECT_ID="$INFISICAL_PROJECT_ID" \
  --build-arg INFISICAL_ENV="$INFISICAL_ENV" \
  --build-arg INFISICAL_DOMAIN="$INFISICAL_DOMAIN" \
  -t my-application:<VERSION> \
  .

In the builder stage:

# File: Dockerfile

ARG INFISICAL_PROJECT_ID
ARG INFISICAL_ENV
ARG INFISICAL_DOMAIN

RUN --mount=type=secret,id=infisical_token,required=true \
    export INFISICAL_TOKEN="$(cat /run/secrets/infisical_token)" && \
    export INFISICAL_DOMAIN="$INFISICAL_DOMAIN" && \
    infisical run \
      --projectId="$INFISICAL_PROJECT_ID" \
      --env="$INFISICAL_ENV" \
      --path="/" \
      -- pnpm build

The access token gets mounted only for that build instruction instead of landing in a normal image layer or build argument. Keep in mind that any value your framework deliberately marks as public, like NEXT_PUBLIC_* in Next.js, is meant to end up in the browser bundle. BuildKit protects the Infisical token here, not values you've already decided should be public.

Step 24: Separate application paths when necessary

For a single application process, storing secrets at the project root is usually enough:

/

As the architecture grows, folders can separate access:

/
├── app
├── workers
├── migrations
└── automation

The web process might receive /app, a background worker /workers, and a migration job /migrations, regardless of what language each of those components is written in. Infisical supports injecting secrets from one or several paths:

infisical run \
  --path="/app" \
  --path="/shared" \
  -- pnpm start

Don't build out a complicated folder hierarchy before you actually have different permission requirements. Folders earn their place once genuinely separate workloads need different subsets of secrets.

Step 25: Rotate a machine identity credential

To rotate the production Client Secret, generate a new Client Secret for the existing machine identity, add it to /etc/my-application/infisical.env, restart the application, confirm it starts correctly, and revoke the old Client Secret. The new process authenticates with the new bootstrap credential immediately. None of this requires rotating the database password, storage key, or any other application secret just because the machine identity credential changed, which is one of the main benefits of separating application secrets from machine authentication in the first place.

Step 26: Back up Infisical correctly

The PostgreSQL database contains the persistent Infisical data. Create a dump:

cd /opt/infisical

docker compose \
  -f docker-compose.prod.yml \
  exec -T db \
  pg_dump \
    -U infisical \
    infisical \
  | gzip \
  > "infisical-$(date +%F-%H%M%S).sql.gz"

The official Docker Compose guide identifies the PostgreSQL volume as the critical persistent store and provides pg_dump as the backup mechanism, but the database alone isn't the complete recovery plan. Your deployment also depends on /opt/infisical/.env, which contains ENCRYPTION_KEY, AUTH_SECRET, POSTGRES_PASSWORD, and SITE_URL. Because ENCRYPTION_KEY is required for Infisical's own encryption and decryption operations, a working recovery plan needs both the database backup and the original platform encryption key together.

Back up the following through an encrypted backup system: the PostgreSQL dump, /opt/infisical/.env, docker-compose.prod.yml, the Nginx configuration, TLS and DNS recovery information, and the pinned Infisical version. Keep the only copy off the Infisical VPS itself, and actually test restoring it. An untested backup is a guess, not a recovery plan.

Step 27: Plan for Infisical availability

Without --watch, infisical run retrieves secrets when the application starts and injects them into the new process. Once an application is running, its environment variables already sit in process memory, so a temporary Infisical outage won't stop that existing process. It can, however, block a new deployment, an application restart, a container replacement, a server reboot, a migration command, or a new worker from starting, no matter what that worker happens to run.

That's why the Infisical instance itself needs monitoring, database backups, resource headroom, controlled upgrades, a documented restore process, and a stable domain with a valid TLS certificate. A secrets manager removes configuration sprawl, and it also becomes part of your deployment control plane, so it deserves the same operational care as anything else on that critical path.

Common problems

The CLI connects to Infisical Cloud instead of your instance

Set the self-hosted domain:

export INFISICAL_DOMAIN="https://secrets.example.com"

Or add it to .infisical.json:

{
  "domain": "https://secrets.example.com"
}

The server receives 401 or 403

Check whether the Client ID is correct, whether the Client Secret is current, whether the identity was actually added to the project, and whether it has access to the selected environment and folder path. Authentication and project access are separate steps, so a machine identity can authenticate successfully and still lack access to a project.

Local development works, but production doesn't

Check INFISICAL_PROJECT_ID, INFISICAL_ENV, INFISICAL_DOMAIN, INFISICAL_PATH, the production machine identity's permissions, and outbound HTTPS connectivity from the server. The staging identity shouldn't be assumed to have production access just because it exists in the same project.

A changed secret isn't being picked up

Restart the process:

sudo systemctl restart my-application

Or recreate the container:

docker compose \
  -f docker-compose.production.yml \
  up -d \
  --force-recreate

Environment variables don't mutate inside an already running process, in Node.js or anywhere else.

A build-time value like NEXT_PUBLIC_* is still old

Rebuild the application. Next.js freezes NEXT_PUBLIC_ values during next build, so restarting the existing build artifact won't pick up a new value; the build has to run again.

The database was restored, but secrets can't be read

Confirm the restored deployment uses the original ENCRYPTION_KEY. A database dump without the matching encryption configuration is an incomplete recovery package.

Infisical works locally but not behind Nginx

Check:

curl -fsS http://127.0.0.1:8080/api/status
curl -fsS https://secrets.example.com/api/status
sudo nginx -t
sudo journalctl -u nginx --tail=100

Also confirm that SITE_URL=https://secrets.example.com matches the actual public URL.

What changed compared with .env files

Before this setup, a developer laptop held .env.local, the staging VPS held .env.staging, the production VPS held .env.production, and the CI runner held its own copy of the production values, all independently. After this setup, Infisical holds development, staging, and production centrally, developers authenticate with a personal login, and the staging and production servers authenticate through their own machine identities.

The application code stays just as simple as it was before:

process.env.DATABASE_URL
process.env.PAYLOAD_SECRET
process.env.S3_SECRET_ACCESS_KEY

What changed is entirely operational: one source of truth, consistent key names, explicit environment separation, separate human and machine access, revocable server credentials, a documented startup workflow, and a repeatable recovery model, none of which depends on which framework or language sits on top of it.

FAQ

Does Infisical only work with Node.js applications? No. Infisical's CLI wraps any command through infisical run -- <command>, so it works the same way for a Python, Go, Ruby, or PHP process as it does for Next.js or Payload. The examples here use Node.js because that's the stack I run, but the pattern generalizes directly.

Do I need separate Infisical projects for separate applications? Usually yes, one project per application keeps environments and access boundaries clean, especially when different applications belong to different clients. A small internal toolset with shared ownership can sometimes live in one project with folders separating the pieces, but that's a judgment call based on who needs access to what.

What's the actual difference between Infisical and a tool like Vault? Infisical focuses on a simpler, Vercel-like mental model of projects, environments, and secrets, with a CLI and dashboard that get you running quickly. HashiCorp Vault and OpenBao add dynamic credentials, PKI, and more advanced policy engines, at the cost of more operational complexity. Most small-to-mid-size teams get everything they need from Infisical without touching Vault's extra surface area.

Can I run Infisical without Docker? The official deployment path is Docker Compose, which is also the path documented and supported by Infisical itself. Running it another way is possible in principle but puts you outside the tested deployment model, so I'd stick with Docker Compose unless you have a specific reason not to.

What happens to my running application if the Infisical server goes down? Nothing, as long as the application is already running, since its environment variables live in process memory once the process has started. An Infisical outage blocks new deployments, restarts, and container replacements until the instance comes back, which is exactly why it needs its own monitoring and backup plan.

Conclusion

Self-hosting Infisical doesn't remove environment variables from the picture. It gives them a proper management and delivery system that works the same way no matter what's consuming them. Developers authenticate as people, application servers authenticate as machine identities, staging and production receive separate values, and the application itself keeps reading standard environment variables without getting tightly coupled to a vendor-specific SDK.

The critical implementation decisions carry across any stack: run Infisical on dedicated infrastructure, put it behind HTTPS, pin the deployed versions, keep the backend port private, separate development, staging, and production, use Universal Auth for VPS workloads, store only restricted bootstrap credentials locally, restart production explicitly after secret changes, handle build-time values where your framework requires it, and back up both PostgreSQL and the Infisical encryption configuration together.

The result is a provider-neutral secrets workflow that works across local development, systemd, Docker, and whatever application framework you're actually running, Next.js and Payload CMS included.

For the broader reasoning behind this setup, read How to Manage Environment Variables and Secrets Across Environments. For the complete application deployment layer, read Self-Host Next.js and Payload on VPS: Complete Guide.

Let me know in the comments if you have questions, and subscribe for more practical development guides.

Thanks, Matija

I run a mix of Next.js and Payload CMS projects for different clients, and almost none of them live on a single host anymore. A typical engagement now spans a Vercel-hosted frontend, a self-hosted Payload instance on a VPS, a managed Postgres database, S3-compatible storage, and an n8n automation server, each with its own staging and production credentials. Once I hit four or five projects with that shape, keeping track of which .env.production file had the current database password stopped being realistic. This article covers the reasoning behind moving to a real secrets manager, and the next one in the series covers the actual Infisical setup for Next.js and Payload.

The problem starts small and stays small for a while

Every project begins the same way. You create a .env file, drop in a database connection string, generate an application secret, paste in a few API keys, and start building.

# File: .env.local
DATABASE_URL=postgresql://localhost/my-app
PAYLOAD_SECRET=development-secret
S3_ACCESS_KEY_ID=example
S3_SECRET_ACCESS_KEY=example

For one developer running one application on one machine, this setup does the job completely.

The trouble shows up once the application grows a staging environment, a production server, a second developer, a CI pipeline, background workers, or a scheduled job hosted somewhere else. Copying .env files between machines works for a while, and then it quietly turns into a liability, because nobody can say with confidence which file on which machine holds the value that is actually live in production.

Environment variables are a delivery mechanism, not a management system

An environment variable is just a value handed to a running process. In a Node.js app you read it through process.env:

// File: src/lib/env.ts
const databaseUrl = process.env.DATABASE_URL
const payloadSecret = process.env.PAYLOAD_SECRET

The application itself has no idea where that value came from. It could have arrived through a local .env file, Docker Compose, a systemd unit, Vercel, Cloudflare, AWS Secrets Manager, a CI pipeline, or a self-hosted secrets manager. process.env looks identical either way.

That's the part worth internalizing early: environment variables describe how configuration reaches your code. The governance around where that configuration is stored, who can see it, and how it gets rotated is a separate concern that a .env file was never built to handle.

Configuration and secrets need different treatment

Not every environment variable deserves the same level of protection. Values like these are normal configuration:

# File: .env
APP_NAME=CanPrev
DEFAULT_LOCALE=en
LOG_LEVEL=info
PUBLIC_SITE_URL=https://www.example.com

These can live in Git if the team wants them versioned alongside the code. Values like these are secrets:

# File: .env (do not commit)
DATABASE_URL=postgresql://user:password@database/app
PAYLOAD_SECRET=...
BREVO_API_KEY=...
S3_SECRET_ACCESS_KEY=...
STRIPE_SECRET_KEY=...

A secret grants access, signs data, decrypts something, or proves identity. Someone who gets hold of one can reach a database, send email under your name, modify storage, or impersonate a service. Configuration benefits from visibility and version history. Secrets need restricted access, encryption, rotation, and a controlled delivery path. Managing both categories through a pile of manually copied .env files tends to blur that distinction until it disappears entirely.

How .env files turn into secret sprawl

There's nothing wrong with using a .env file for local development. The trouble is relying on it as the source of truth once the system looks like this:

Application
├── Developer laptop
├── Staging VPS
├── Production VPS
├── CI pipeline
├── Background worker
└── n8n automation

Each of those needs some combination of DATABASE_URL, PAYLOAD_SECRET, REDIS_URL, S3_ACCESS_KEY_ID, S3_SECRET_ACCESS_KEY, SMTP_PASSWORD, BREVO_API_KEY, and INTERNAL_WEBHOOK_SECRET. Without a central system, the same secrets end up copied into .env.local, .env.staging, .env.production, docker-compose.yml, GitHub Actions secrets, VPS shell configuration, systemd service files, deployment scripts, password managers, Slack messages, and internal docs. At that point nobody can say for certain which copy is current. That's secret sprawl, and it grows quietly because each individual copy felt reasonable when someone made it.

The failure modes are mostly boring, not dramatic

Committing a production .env file to Git gets attention because it's an obvious mistake, and it's a real one since the secret can linger in repository history and in clones long after the file is deleted. Most of the damage from poor secret management shows up in quieter, everyday ways instead.

Environment drift. Staging uses S3_BUCKET=project-staging while production uses AWS_BUCKET=project-production, and a deployment that works fine in staging fails in production because the configuration model drifted without anyone noticing.

Unknown ownership. An API key stops working and nobody can say who created it, which account owns it, which services depend on it, or whether rotating it will break something else.

Stale access. A contractor leaves the project but still has last quarter's production .env file sitting on a laptop. Revoking a GitHub permission does nothing to claw back credentials that were already copied elsewhere.

Shared production credentials. Several servers and developers all authenticate with the same database password or storage key, so revoking access for one person means rotating a credential everyone depends on.

Unreliable deployments. A new VPS goes up and someone has to rebuild its configuration from an old server, a password manager, and a scattering of chat messages, which makes the deployment depend on memory rather than a repeatable process.

Inconsistent local environments. A developer loses hours debugging an app before realizing their .env.local still points at an endpoint that was decommissioned months ago.

Build-time versus runtime confusion. This one shows up constantly in Next.js. A server-only value like DATABASE_URL gets injected when the process starts. A value prefixed with NEXT_PUBLIC_ gets baked into the client bundle at build time, and needs to exist when next build runs rather than when the server starts. Treating both the same way produces broken deployments and occasionally leaks a secret into a public bundle.

What a proper secrets-management setup actually provides

A good system does more than hide values behind a login. It builds a workflow around storing, accessing, and delivering them.

A single authoritative location holds each secret, so instead of asking a teammate to send over the current production .env, everyone opens the project's production environment inside the secrets manager.

Environments stay explicitly separated:

My application
├── Development
├── Staging
└── Production

The same key can exist in each environment with a different value:

Development
DATABASE_URL=postgresql://localhost/app

Staging
DATABASE_URL=postgresql://staging-database/app

Production
DATABASE_URL=postgresql://production-database/app

Humans and machines get distinct identities. A developer might have permission to view and edit development secrets. A production server authenticates as itself with read-only access to production secrets, rather than borrowing a developer's personal login.

Access follows least privilege: a CanPrev staging server can read CanPrev staging secrets and nothing beyond that, so compromising one server doesn't hand over every other project the team runs.

Access is revocable per identity. When a server gets replaced or a teammate leaves, that one identity gets revoked without rotating every credential across the organization.

Delivery stays simple on the application side. Code keeps reading process.env.DATABASE_URL exactly as before; the secrets manager handles fetching the right value and injecting it when the process starts, so the application never gets coupled to a specific secrets platform.

Rotation and history are tracked, so the team knows which value is current and which services need a restart when it changes. More advanced platforms add version history, approval workflows, audit logs, and automated rotation on top of that.

Recovery gets planned for too. The secrets manager becomes important infrastructure in its own right, and its encryption keys, database, and backups need a recovery plan just like anything else you'd call critical.

What this looks like once it's running

A central setup for a small agency might look like this:

Secrets manager
├── CanPrev website
│   ├── Development
│   ├── Staging
│   └── Production
│
├── CanPrev DAM
│   ├── Development
│   ├── Staging
│   └── Production
│
└── Internal automation
    ├── Development
    ├── Staging
    └── Production

A developer authenticates through the CLI and runs:

secrets-tool run --environment=development -- pnpm dev

The development secrets get fetched and injected into that new process. A production VPS authenticates with its own machine identity, something like canprev-website-production-vps, scoped to read-only access on the CanPrev website production environment. When the application starts:

secrets-tool run --environment=production -- node server.js

The app still reads process.env the same way it always did. There's no custom secret-fetching logic scattered through the codebase.

You may already be using a secrets manager without the name

Managed hosting platforms made this workflow familiar long before anyone called it "secrets management."

Vercel lets you define variables per development, preview, and production environment, and because it owns the build and runtime, it injects the right values automatically during deployment. That's convenient and usually plenty when the entire application runs on Vercel. It starts to feel thin once the system also includes a self-hosted Payload instance, separate worker servers, n8n, or anything deployed outside Vercel, since Vercel's variable management is scoped to Vercel projects rather than an organization's whole infrastructure.

Cloudflare offers a similar model for Workers and Pages, and it works well for the same reason: Cloudflare owns the runtime that receives the values.

AWS Secrets Manager centralizes secrets and integrates with AWS IAM, so applications authenticate through AWS identities and pull only what they're permitted to see. That's a strong option when most of the infrastructure already runs inside AWS, and the same logic applies to Google Secret Manager and Azure Key Vault. It becomes less convenient once applications are spread across unrelated VPS providers, local machines, and client-owned environments that have no natural AWS identity to authenticate with.

Comparing the main categories of tools

There's no universally correct choice here. The right tool depends on where your applications run, how granular your access control needs to be, and how much infrastructure your team is willing to operate.

Staying with the hosting platform

An application fully hosted on Vercel may not need anything beyond Vercel's own environment variables, since the platform already covers environment separation, build integration, runtime injection, team permissions, and CLI access. Layering an external secrets manager on top can add more overhead than value here. That calculation changes once the system crosses platform boundaries, for example a Next.js frontend on Vercel, Payload on DigitalOcean, a managed Postgres database, S3-compatible storage, and an n8n VPS running automation. At that point secrets live across several dashboards and no single system sees the whole picture.

Using the cloud provider's secret manager

AWS Secrets Manager, Google Secret Manager, and Azure Key Vault fit naturally for a company already committed to one cloud ecosystem, mainly because of identity integration: an AWS workload can receive an IAM role and pull secrets without a permanent access key sitting on the server. That's a strong security model as long as the workload runs inside that cloud. Pointing an external DigitalOcean or Hetzner server at AWS Secrets Manager works technically, but that server still needs its own secure way to authenticate into AWS, which means the architecture now depends on a cloud provider that isn't hosting the application.

Using a managed provider-neutral platform

A managed secrets platform can serve as the common source of truth across local development, GitHub Actions, Vercel, DigitalOcean, Hetzner, AWS, Kubernetes, and plain Node.js processes, with the vendor handling the central service, database, updates, and uptime. That takes operational work off your plate in exchange for a subscription cost and an external dependency, which is a reasonable trade for a lot of teams.

Self-hosting a secrets manager

A self-hosted platform gives you a Vercel-like interface for environments and secrets while staying independent of whatever hosts the application. This fits organizations running multiple applications across different VPS providers who want to keep control of the underlying platform. Infisical, OpenBao, and HashiCorp Vault are the common options here.

Infisical provides projects, environments, a dashboard, a CLI, machine identities, and integrations for delivering secrets into applications, and its mental model tracks closely with Vercel's:

Project
├── Development
├── Staging
└── Production

Infisical doesn't host your application; you connect it explicitly to Docker, systemd, CI, or a local dev command. That makes it a practical choice for teams that want a central, provider-neutral secrets manager without taking on the full operational weight of a Vault-style system.

OpenBao and HashiCorp Vault go further, supporting dynamic database credentials, time-limited secret leases, PKI, certificate issuance, encryption services, and advanced authentication policies. Those capabilities matter in larger or more security-sensitive environments, and they come with real design, maintenance, and operational overhead. For a team mainly trying to stop copying .env files between VPSs, that overhead is often more infrastructure than the problem calls for.

Encrypting secrets in Git with SOPS

SOPS skips the central server entirely. You store encrypted configuration files in Git instead:

secrets/
├── development.enc.env
├── staging.enc.env
└── production.enc.env

The encrypted files version safely in the repository, while approved developers and servers hold the keys needed to decrypt them, using age, AWS KMS, Google Cloud KMS, Azure Key Vault, or PGP. This suits infrastructure-as-code workflows and smaller teams comfortable operating close to Git. Its friction shows up operationally: managing access, revoking machines, rotating encryption recipients, and delivering secrets dynamically all take more manual effort than a central platform handles for you. SOPS also pairs well alongside a full secrets manager, protecting the bootstrap credentials needed to deploy that manager in the first place.

How to choose

The simplest rule is to pick the system closest to where your application already runs. Reach for platform environment variables when the application runs entirely on one managed platform and you don't need a central view across external services. Reach for a cloud-native secrets manager when most workloads sit in one cloud provider and its identity system already matters more to you than portability. Reach for a managed provider-neutral platform when applications span several providers, you'd rather not operate the secrets service yourself, and the subscription cost is acceptable. Reach for a self-hosted secrets manager when applications span multiple VPSs, you want one central source of truth that you own, and you're prepared to operate and back it up. Reach for SOPS when Git already anchors your infrastructure workflow, deployments happen through controlled changes, and your team is comfortable managing encryption keys directly.

Why Infisical fits the projects I run

Most of what I build now includes more than one deployment target: a Next.js frontend, Payload CMS, Postgres, Redis, object storage, background jobs, n8n, external APIs, a staging VPS, a production VPS, and local development, often owned by different clients and hosted by different providers. The Vercel-style mental model of projects and environments is still the right one, it just needs to exist independently of Vercel itself.

Infisical fits that gap well. It can be self-hosted, gives you a central dashboard, separates projects and environments cleanly, issues separate identities to humans and servers, and its CLI injects variables into ordinary processes. Next.js and Payload keep reading process.env exactly as before, and none of it requires the application to run on a particular cloud.

The workflow ends up feeling familiar. Locally:

infisical run --env=dev -- pnpm dev

On staging:

infisical run --env=staging -- node server.js

In production:

infisical run --env=prod -- node server.js

The application code stays conventional:

// File: src/lib/env.ts
const databaseUrl = process.env.DATABASE_URL

Infisical handles where that value lives, who can see it, and which environment gets it.

The secret-zero problem doesn't fully disappear

There's one detail worth naming directly. A generic VPS still needs some initial way to authenticate to the secrets manager itself. Rather than storing every application secret locally, the server holds one restricted machine credential:

# File: .env (VPS bootstrap only)
INFISICAL_CLIENT_ID=...
INFISICAL_CLIENT_SECRET=...

That identity might be scoped to read-only access on the CanPrev website production environment and nothing else. This is called the secret-zero problem, and it can't be eliminated entirely on an ordinary VPS. It can be narrowed down to one revocable, tightly scoped credential, which is a far smaller blast radius than a complete production .env file carrying database, storage, email, and API credentials all at once.

What still belongs in the repository

Moving to a secrets manager doesn't mean every setting leaves Git. Keep a .env.example documenting the variables the application expects:

# File: .env.example
DATABASE_URL=
PAYLOAD_SECRET=
S3_BUCKET=
S3_ACCESS_KEY_ID=
S3_SECRET_ACCESS_KEY=
BREVO_API_KEY=

Use names and safe placeholder values here, never real credentials. Non-sensitive configuration can stay in the repo too:

# File: .env
DEFAULT_LOCALE=en
LOG_LEVEL=info
FEATURE_SEARCH_ENABLED=true

The point isn't hiding every setting from Git. It's centralizing the sensitive values and building a predictable, repeatable way to deliver them.

A migration path that doesn't require a big-bang cutover

Moving to a secrets manager works best as a sequence rather than one large infrastructure change:

1. Inventory the current environment variables.
2. Separate secrets from public configuration.
3. Identify where every current value is stored today.
4. Create development, staging, and production environments centrally.
5. Migrate local development first.
6. Integrate the staging deployment.
7. Test application restarts and failed secret retrieval.
8. Integrate production.
9. Remove old plaintext files.
10. Rotate credentials that were previously shared widely.

Start in a non-critical environment and confirm the workflow holds up before touching production. Importing a .env file into a new dashboard is the easy part; the actual improvement comes from defining ownership, access boundaries, rotation, and recovery around it.

FAQ

Do I need a secrets manager if I only deploy to Vercel? Probably not yet. Vercel already separates development, preview, and production variables and injects them automatically at build and runtime. A separate secrets manager earns its place once your infrastructure spreads beyond what Vercel controls, like a self-hosted Payload instance or a background worker on its own VPS.

What's the difference between a secret and regular configuration? A secret grants access, signs data, decrypts something, or proves identity, so exposure lets someone reach a resource they shouldn't. Configuration values like a locale code or a log level carry no access risk on their own and can usually live safely in Git.

Can NEXT_PUBLIC_ variables come from a secrets manager too? They can, but remember that anything prefixed NEXT_PUBLIC_ gets baked into the client bundle at build time rather than read at runtime. Your secrets manager needs to inject those values into the next build step specifically, not just into the running server process.

Does self-hosting Infisical remove all local secrets from my servers? No. Each server still needs one bootstrap credential to authenticate to Infisical itself, which is the secret-zero problem. What changes is the blast radius: that one credential can be scoped to read-only access on a single environment, instead of a full .env file carrying every credential the application uses.

Is SOPS a replacement for a secrets manager like Infisical or Vault? It can be, especially for smaller teams already running an infrastructure-as-code workflow through Git. It can also complement a full secrets manager by protecting the bootstrap credentials needed to deploy that manager in the first place.

Wrapping up

Copying .env files between machines feels harmless right up until a second developer, a staging server, or a CI pipeline enters the picture, at which point it turns into an undocumented deployment process with weak access control. A proper secrets-management setup gives every environment a defined source of truth, lets developers authenticate as themselves and servers authenticate as machines, and grants each identity only the access it actually needs. The application code doesn't change; it keeps reading process.env exactly as before. What changes is how those values get governed and delivered.

The next article in this series moves from strategy to implementation: self-hosting Infisical on a VPS, setting up projects and environments, creating human and machine identities, connecting a local Next.js and Payload dev environment, injecting secrets into Docker and systemd, separating build-time from runtime variables, and migrating away from existing production .env files.

Let me know in the comments if you have questions, and subscribe for more practical development guides.

Thanks, Matija

I set this up recently on a client project where the collaboration and review process happens on GitHub, but the client's internal tooling requires a mirror on Bitbucket. Rather than maintaining two separate clones or relying on a manual copy-paste workflow, I configured one local repo with two remotes and a couple of scripted push commands. This guide documents that exact setup, including the SSH key routing, the branch-naming quirks between hosts, and the commands I actually run day to day.

Why One Repo Can Talk to Several Hosts

Git itself has no concept of a "home" host. Your local .git directory holds the full history, and GitHub, Bitbucket, and GitLab are simply named bookmarks pointing at other copies of that same history. A remote is just a label attached to a URL.

Local repo (main branch)
      |
      ├── origin     → GitHub
      ├── bitbucket  → Bitbucket
      └── gitlab     → GitLab (optional)

Fetching pulls commits from a remote into your machine. Pushing sends commits from your machine to a remote. The remotes never talk to each other directly, so if you push to GitHub and forget Bitbucket, Bitbucket simply falls behind until you push there too.

Checking What You Already Have

Before adding anything, see what's configured:

git remote -v
git branch -vv
git status

A repo with two remotes looks like this:

origin     https://github.com/org/repo.git (fetch)
origin     https://github.com/org/repo.git (push)
bitbucket  git@bitbucket.org:workspace/repo.git (fetch)
bitbucket  git@bitbucket.org:workspace/repo.git (push)

* main  abc1234 [origin/main] latest commit message

The [origin/main] marker tells you which remote branch your local main tracks. That's the target for a plain git pull or git push with no remote name specified.

Adding a Second (or Third) Remote

Create the empty repository on each host first, then point your local project at it.

# HTTPS
git remote add origin https://github.com/ORG/REPO.git
git remote add bitbucket https://bitbucket.org/WORKSPACE/REPO.git

# SSH (recommended for daily use)
git remote add origin git@github.com:ORG/REPO.git
git remote add bitbucket git@bitbucket.org:WORKSPACE/REPO.git

To change a URL later, or rename or remove a remote:

git remote set-url bitbucket git@bitbucket.org:WORKSPACE/REPO.git
git remote rename origin github
git remote remove gitlab

The convention I use: GitHub stays origin because it's canonical for pull requests and daily pushes, and every other host gets named after itself (bitbucket, gitlab).

Routing SSH Keys per Host

If you use separate accounts across hosts, or you just want clean revocation, generate a dedicated key per host and route it through ~/.ssh/config:

Host github.com
  HostName github.com
  User git
  IdentityFile ~/.ssh/id_ed25519_github
  IdentitiesOnly yes

Host bitbucket.org
  HostName bitbucket.org
  User git
  IdentityFile ~/.ssh/id_ed25519_bitbucket
  IdentitiesOnly yes

Generate a new key and add the public half to the host's UI:

ssh-keygen -t ed25519 -C "bitbucket-work" -f ~/.ssh/id_ed25519_bitbucket

Confirm each connection works before you push anything:

ssh -T git@github.com
ssh -T git@bitbucket.org

If you see a host key warning, register the host once:

ssh-keyscan -t ed25519,rsa bitbucket.org >> ~/.ssh/known_hosts

Pushing to Only One Remote

This is the workflow you'll use most. Always name the remote explicitly so there's no ambiguity about where a branch, tag, or deletion is headed.

git push origin main       # GitHub only
git push bitbucket main    # Bitbucket only

Setting the default upstream

git push -u origin main sets origin as the default target for a plain git push going forward. Run this once for GitHub and skip -u for the mirror, so an unqualified git push never accidentally lands on the wrong host:

git push -u origin main
git push bitbucket main

If the upstream ever gets pointed at the wrong remote, restore it directly:

git branch -u origin/main main

Feature branches, tags, and deletions

Each of these needs the remote spelled out too, since Bitbucket or GitLab won't see anything you don't explicitly push:

git push -u origin feature/i18n     # PR branch on GitHub
git push bitbucket feature/i18n     # same branch mirrored to Bitbucket

git push origin v1.2.0              # a single tag
git push origin --delete old-branch # remove a branch on one remote only

Fetching and Comparing Remotes

git fetch origin
git fetch bitbucket
git fetch --all

To see what's different between two remotes without merging anything:

git fetch --all
git log --oneline origin/main..bitbucket/main
git log --oneline bitbucket/main..origin/main

Pushing to Both Remotes at Once

For a repo you mirror on every push, there are three ways to automate it.

The alias approach is what I use, since it keeps each push visible in the terminal output:

# ~/.zshrc
alias gpush-all='git push origin HEAD && git push bitbucket HEAD'
alias gpush-gh='git push origin HEAD'
alias gpush-bb='git push bitbucket HEAD'

The main vs master Trap

Hosts don't agree on default branch names, and this catches people off guard the first time they mirror an existing repo.

Your local branch might be main while an old, empty master branch is still sitting on Bitbucket from when the repo was first created. The Bitbucket UI path /src/master/ will show that stale branch, not the one you're actually pushing to.

Check what a remote actually has:

git ls-remote bitbucket

To make main the canonical branch on a host that still defaults to master, either force master to match main's content (only if the old master history is disposable):

git push bitbucket main:master --force

Or push main on its own and change the host's default branch setting through its UI:

• GitHub: Settings → General → Default branch
• Bitbucket: Repository settings → Repository details → Advanced → Main branch
• GitLab: Settings → Repository → Default branch

Git can't change a host's default branch over the git protocol itself. That setting lives in the host's own configuration.

First Sync When the Remote Already Has Commits

If the host auto-created a README, license, or .gitignore, your local history and the remote's history may have no common ancestor. Check before pushing:

git fetch bitbucket
git log --oneline --graph --all --decorate | head -40

If the remote's content is disposable, force your history onto it:

git push bitbucket main --force

If you need to keep what's already there, merge the histories explicitly:

git pull bitbucket main --allow-unrelated-histories
git push bitbucket main

Avoid --force on any branch other people rely on unless the team has agreed on it first.

My Daily Workflow for This Setup

1. Develop and commit locally, same as any single-remote repo.
2. Open pull requests and do code review on GitHub (origin), which stays canonical.
3. After a merge, or whenever the client needs the mirror current, sync Bitbucket:

git checkout main
git pull origin main
git push origin main
git push bitbucket main

4. Confirm the upstream is still GitHub:

git branch -u origin/main main

A Note on CI

Pushing the same commits to two hosts does not duplicate your CI pipelines. GitHub Actions and Bitbucket Pipelines are separate systems, and each one only runs if it's configured on that specific host. If Vercel or another deploy target is bound to GitHub, mirroring to Bitbucket won't trigger a second deployment unless you set that up independently.

FAQ

Does pushing to origin automatically update bitbucket? No. Remotes never sync with each other. Each git push only reaches the remote you name, so a mirror only stays current if you push to it as a separate step.

What happens if I run git push with no remote name? It goes to whichever remote your current branch tracks as its upstream, which you can check with git branch -vv. Set this explicitly with git push -u <remote> <branch> so there's no guessing.

Can I set up automatic mirroring so I never have to push twice? Yes, using a dual push URL on one remote name (git remote set-url --add --push origin <second-url>) or a CI job that mirrors on merge. A shell alias is the simplest version if you're doing this manually.

Why does Bitbucket show master when I've been working in main the whole time? Bitbucket creates a default branch when the repository is first made, and that's often still master unless changed. Check git ls-remote bitbucket to see exactly which branches exist there, then update the host's default branch setting in its UI.

Is it safe to force-push a mirror branch? Force-pushing is fine on a mirror that no one else pulls from directly, since you're just overwriting a copy. Treat any branch other people build on as off-limits for force-pushing regardless of which remote it lives on.

Wrapping Up

A single local repository can push to as many hosts as a project needs, and the pattern stays the same regardless of how many remotes you add: name each one explicitly, decide which host is canonical for reviews, and push to the others as deliberate mirroring steps rather than assuming they'll stay in sync on their own. Once the remotes and SSH routing are set up, the daily commands are just git push origin main followed by git push bitbucket main.

Let me know in the comments if you have questions, and subscribe for more practical development guides.

Thanks, Matija

At first glance, it looks like Payload has launched a complete DAM product alongside its CMS.

That is not quite the current reality.

Payload already provides many of the technical foundations needed to build a digital asset management system. You can upload files, generate image sizes, organize assets, add custom metadata, control access, connect cloud storage and customize the entire admin interface.

But Payload does not currently provide a finished, out-of-the-box DAM comparable to platforms such as Bynder, Brandfolder or Canto.

It does not even provide a public DAM starter template yet.

The more accurate interpretation is:

Payload is positioning itself as a framework for building a custom DAM, while Payload 4.0 is expected to package and improve those capabilities into a more complete starting point.

In this article, I will separate what Payload supports today from what is still planned, and explain what this means if you are considering Payload for digital asset management.

[!NOTE] This article reflects the public status as of July 21, 2026. Payload 4.0 is still under development, so individual features and timelines may change.

Why this distinction matters

Payload’s official digital asset management page describes a system for organizing, sharing and governing digital assets alongside website content.

The page highlights capabilities such as:

• Asset organization
• Team sharing
• Asset lifecycle management
• Version control
• Audit logs
• Field-level access control
• Enterprise security
• Custom workflows

Those are all reasonable outcomes to build with Payload.

However, the page is also labelled Coming Soon.

That label matters because many of the features normally associated with a mature DAM are not currently available as one cohesive Payload product.

The page is describing the solution Payload wants to support, not necessarily a finished module that can be enabled in an existing project.

Payload’s own DAM RFC makes this clearer.

In May 2026, the Payload team published RFC #16681, outlining planned improvements to its open-source digital asset management capabilities.

The RFC proposes:

• Video previews with controls
• PDF previews
• Video and PDF thumbnails
• Localized files
• File versioning
• A dedicated DAM documentation section
• A new DAM starter template
• On-demand image resizing
• Expiring asset-sharing links
• Usage references showing where assets are used

These are described as proposed changes.

In other words, the RFC confirms that Payload’s complete DAM experience is still being assembled.

Is Payload currently a DAM?

The practical answer is:

Payload can be used to build a DAM, but Payload is not currently a finished DAM product.

Payload is a full-stack application framework with a CMS and admin panel. Its code-first architecture makes it possible to model almost any content, workflow or internal application.

That includes digital asset management.

But there is a difference between having the primitives required to build a DAM and having a complete DAM available out of the box.

Payload gives developers the primitives.

The developer still needs to design and implement the final asset-management system.

What Payload supports today

Payload already includes several capabilities that are genuinely useful for digital asset management.

Upload collections

Any Payload collection can be configured as an upload-enabled collection.

This allows you to manage files as structured database records rather than treating them as anonymous objects in a storage bucket.

An uploaded asset can contain the standard file information alongside custom fields such as:

• Asset title
• Description
• Alternative text
• Copyright owner
• Licence information
• Brand
• Campaign
• Product
• Region
• Language
• Approval status
• Expiry date
• Usage restrictions
• Internal notes

This is one of Payload’s main strengths.

The media schema is not fixed by a vendor. You can model assets according to the actual requirements of your organization.

Image processing

Payload supports image resizing and generated image sizes.

A project can automatically generate different versions of an image for thumbnails, cards, product pages, mobile views or large desktop layouts.

Payload also supports focal-point selection and image cropping.

This makes it suitable for website and application media workflows where one source image needs to be used in several contexts.

However, more advanced transformation workflows may still require custom hooks, background jobs or an external image-processing service.

Cloud storage

Payload provides official storage adapters for services including:

• Amazon S3
• Cloudflare R2
• Google Cloud Storage
• Azure Blob Storage
• Vercel Blob
• S3-compatible storage providers

This means the asset files do not need to live on the application server.

For example, a Payload project can store asset metadata in PostgreSQL while storing the original files and generated sizes in an S3-compatible object-storage service.

This is a sensible architecture for a custom DAM because it separates the application layer from binary file storage.

Access control

Payload’s access-control system is one of its strongest DAM foundations.

Access rules can be defined at the collection, document and field level.

You can create rules such as:

• Users can only see assets belonging to their brand.
• Marketing users can upload assets but cannot approve them.
• Legal users can edit licence and copyright fields.
• External partners can only access approved assets.
• Regional teams can only see assets assigned to their markets.
• Administrators can manage assets across all brands.
• Public users can download only explicitly published files.

The access rules apply to both the APIs and the Payload admin panel.

This allows the DAM permission model to reflect the organization’s real structure instead of being limited to basic folders and user groups.

Versions and audit information

Payload supports document versions, drafts and autosave.

When versions are enabled, teams can track changes to asset metadata over time, including who changed a record and when it was changed.

This is useful for fields such as:

• Approval status
• Expiry date
• Copyright information
• Product relationships
• Asset categorization
• Availability by region
• Internal ownership

However, document versioning should not automatically be interpreted as complete binary file versioning.

A traditional DAM may preserve every previously uploaded binary file and allow users to restore an earlier asset revision.

Payload’s RFC lists file versioning as a proposed DAM improvement, indicating that this is an area the team still intends to strengthen.

Folders

Payload currently supports folders for organizing documents and uploaded assets.

Folders provide a more familiar browsing interface for editors who do not want to work exclusively with database filters and search.

However, folders should not become the entire asset taxonomy.

A folder can answer:

Where does this asset currently live?

Metadata can answer:

What is this asset, who can use it, where can it be published, when does it expire and what is it related to?

For a serious DAM implementation, folders should complement metadata rather than replace it.

What Payload does not currently provide as one finished system

Payload’s flexibility can sometimes make the line between native functionality and custom implementation difficult to see.

Many advanced DAM requirements are possible with Payload, but possible does not mean included.

The following capabilities should currently be treated as planned or custom implementation work.

A dedicated DAM starter template

Payload’s RFC explicitly proposes a new DAM starter template.

As of July 21, 2026, the official Payload repository contains templates for websites, ecommerce, plugins, blank projects and several infrastructure combinations.

It does not contain a public DAM template.

This means there is currently no official DAM boilerplate that developers can install and immediately adapt.

The DAM use-case page is therefore not advertising an existing template. It is presenting the direction of the product.

Binary file versioning

Payload supports versions for documents, but the RFC separately proposes file versioning.

This distinction is important.

Updating an asset record and replacing the actual underlying file are not necessarily the same operation.

A mature DAM may need to preserve:

• The original file
• Every replacement file
• Transformation history
• Approval history
• The active approved revision
• Previous download URLs
• The relationship between old and new versions

This can be built in Payload today, but it needs to be modelled deliberately.

PDF and video previews

Payload’s current upload interface is primarily optimized around images and general file records.

The RFC proposes richer PDF and video previews, including thumbnails and playback controls.

Until those features are released, projects that require sophisticated media previews may need custom admin components or external processing services.

Expiring sharing links

Temporary public sharing is a standard DAM feature.

A user selects an asset or collection, generates a link, chooses an expiry date and shares it with someone who does not have an account.

Payload can support this architecture through custom collections, access rules and signed URLs.

However, expiring sharing links are listed as a proposed DAM feature rather than a finished native workflow.

Usage references

Before replacing or deleting an asset, editors often need to know where it is being used.

For example:

• Which pages reference this image?
• Which product records use this PDF?
• Is this logo included in an active campaign?
• Which websites are using this file?
• Will deleting this asset break published content?

Payload relationships make it possible to build usage reporting.

But the RFC explicitly proposes usage references as a new feature, meaning there is not yet a complete native DAM interface for this workflow.

Localized files

Payload already supports localized fields.

However, localized files introduce a different requirement: one logical asset may contain a different binary file for each language.

For example:

• An English product brochure
• A French product brochure
• A German product brochure

The DAM RFC proposes direct support for localized files.

Until that lands, teams need to model localized asset variants themselves, perhaps through relationships, arrays or separate asset records.

Asset lifecycle automation

A serious DAM often needs more than a status field.

It may need workflows such as:

• Notify an owner before an asset expires.
• Prevent downloads after licence expiry.
• Archive assets automatically.
• Replace expired assets across connected websites.
• Require legal approval before publication.
• Require a new approval when the binary file changes.
• Restrict an asset to certain countries.
• Record why an asset was withdrawn.
• Prevent the deletion of assets that are still in use.

Payload provides hooks, jobs, access control and custom fields that can implement these rules.

But the lifecycle itself must be designed and built.

External asset portals

Many DAM systems provide branded portals where distributors, agencies, retailers or partners can download approved files.

Payload can be used to build this kind of portal because it includes authentication, APIs and access control.

Still, this is a custom application, not a standard Payload screen.

What is coming in Payload 4.0

The DAM work is part of the broader Payload CMS 4.0 redesign.

Payload 4.0 appears to be focused heavily on product maturity, especially the experience of editors and non-technical teams.

For DAM use cases, the main areas to watch are:

• A redesigned upload interface
• Better media previews
• PDF and video support
• File versioning
• Localized files
• On-demand transformations
• Expiring share links
• Usage references
• A dedicated DAM starter template
• Better documentation
• Improved folder and hierarchy interfaces
• Changes to storage-adapter configuration

At least one infrastructure change from the RFC has already landed on Payload’s main branch.

The change moves storage adapters to a dedicated top-level storage configuration property rather than treating them only as plugins.

This should give Payload more control over when storage adapters are initialized and make storage configuration a clearer first-class part of the application.

However, this is an architectural improvement.

It does not mean the complete DAM feature set has shipped.

What the future DAM starter will probably be

When the official starter arrives, it will likely resemble Payload’s other templates.

It will be a codebase designed to accelerate development, not a fixed SaaS product.

A DAM starter could reasonably include:

• An upload-enabled asset collection
• Asset metadata fields
• Folder configuration
• Example access rules
• Cloud-storage configuration
• Asset list and detail views
• File-preview components
• Sharing-link collections
• Usage-reference interfaces
• Example lifecycle statuses
• Seed data
• A frontend or portal example

That would be valuable.

It could reduce weeks of basic implementation and establish standard patterns for the Payload ecosystem.

But organizations would still need to adapt it to their requirements.

A pharmaceutical company, retailer, publisher and manufacturing business will not have the same asset model.

They may differ in:

• Approval requirements
• Product relationships
• Legal restrictions
• Regions
• Languages
• Retention rules
• User roles
• Brand structure
• Distribution channels
• External partners
• Reporting requirements

Payload’s strength is that those rules can be expressed in code.

The trade-off is that someone still has to design them.

Payload DAM compared with a traditional DAM product

The most useful way to evaluate Payload is not simply to ask whether it has DAM features.

The better question is:

Does the organization want to buy a standardized DAM product or build an asset platform around its own workflows?

A traditional DAM platform usually provides:

• A finished user interface
• Established asset workflows
• Sharing portals
• Reporting
• Integrations
• Vendor support
• Less development work
• Faster initial deployment

The trade-offs may include:

• Higher licence costs
• Vendor lock-in
• Limited data-model flexibility
• Integration complexity
• Separate content and asset systems
• Restrictions imposed by the vendor’s workflow model

A Payload-based DAM provides:

• Full ownership of the application
• Full control over the schema
• Custom permissions
• Custom workflows
• Direct relationships between content and assets
• Integration with existing Payload websites or applications
• Flexible hosting
• No mandatory DAM SaaS licence

The trade-offs are:

• More architecture work
• More custom development
• Responsibility for maintenance
• Responsibility for security and infrastructure
• Fewer finished workflows today
• Dependence on your implementation quality

This is why Payload’s DAM page talks about the answer to “build vs buy.”

Payload is primarily the build option.

When Payload makes sense for DAM

Payload is a strong candidate when digital assets need to be tightly connected to other business content.

For example:

• Product images connected to product records
• Brochures connected to markets and languages
• Campaign assets connected to landing pages
• Regulatory documents connected to products
• Brand files shared across multiple websites
• Assets governed by custom approval rules
• Files distributed to selected partners
• Content and assets managed in one application

Payload becomes especially compelling when the organization already uses Payload for its websites, portals or content platform.

Instead of introducing a separate DAM with another authentication system, another permission model and another integration layer, the asset library can become part of the same application.

This can reduce duplication and synchronization work.

When a dedicated DAM product may be better

Payload may not be the right choice when an organization needs a mature DAM immediately and does not want to maintain custom software.

A dedicated DAM platform may be preferable when the requirements include:

• Advanced creative workflows
• Adobe integration
• Large agency ecosystems
• Sophisticated rights management
• Automated video transcoding
• Visual similarity search
• AI tagging available immediately
• Large-scale distribution portals
• Extensive analytics
• Formal vendor support
• A fixed implementation timeline with minimal development

In those situations, the development cost of recreating mature DAM functionality may outweigh the benefits of owning the system.

What teams should build today

Teams do not necessarily need to wait for Payload 4.0.

A practical Payload 3 DAM can already be built with:

• Upload collections
• S3-compatible storage
• Custom metadata
• Access control
• Folders
• Versions
• Drafts
• Hooks
• Jobs
• Custom admin components
• A dedicated asset portal

However, teams should separate requirements into three categories.

Native today

These are capabilities Payload already provides as reliable building blocks:

• File uploads
• Image sizes
• Metadata
• Relationships
• Authentication
• Access control
• Versions
• APIs
• Admin customization
• Cloud-storage adapters

Custom implementation

These can be built today, but they require project work:

• Approval workflows
• Expiry enforcement
• Partner portals
• Usage reports
• Sharing links
• Download analytics
• Duplicate detection
• Binary revision history
• Virus scanning
• Asset replacement workflows
• Rights management
• Notifications

Planned for Payload 4.0

These are areas the Payload team has publicly proposed improving:

• DAM starter template
• File versioning
• PDF previews
• Video previews
• Localized files
• On-demand resizing
• Expiring links
• Usage references
• Dedicated DAM documentation

This separation is important when estimating scope.

A company should not budget a Payload DAM as though it were simply enabling a plugin.

There is real product and implementation work involved.

My current assessment

Payload has a credible foundation for digital asset management.

Its strongest advantages are not the media browser or preview interface.

Its strongest advantages are:

• A flexible data model
• Fine-grained access control
• Full-stack TypeScript
• Extensible admin interfaces
• Direct relationships between assets and content
• Flexible infrastructure
• Open-source ownership

Those are the difficult architectural pieces.

The missing pieces are mostly the finished DAM product experience.

Payload 4.0 appears intended to close some of that gap by improving the upload UI, previews, file handling, sharing and usage visibility.

The upcoming DAM starter could also give teams a much better baseline.

But until those features are released, the honest position is:

Payload is a strong framework for building a custom DAM, not an out-of-the-box DAM product.

That is not necessarily a weakness.

For organizations with unusual content, brand, product or approval requirements, it may be exactly the reason to choose Payload.

For organizations that want a finished asset platform tomorrow, it may be a reason to choose something else.

Final thoughts

Payload’s digital asset management page is best understood as a statement of direction.

The company is clearly investing in DAM as a first-class use case.

The current Payload platform already contains many of the foundations required to build one, including uploads, metadata, access control, versions, folders and cloud storage.

Payload 4.0 is expected to make those foundations more coherent through improved media interfaces, richer previews, file versioning, sharing, usage references and an official starter template.

For now, the distinction remains simple:

• Payload can power a serious DAM today.
• Developers still need to build the actual DAM experience.
• Payload 4.0 should reduce that work.
• The complete out-of-the-box product does not exist yet.

For the wider Payload 4.0 roadmap, including the admin redesign, hierarchies, MCP improvements and experimental framework adapters, read Payload CMS 4.0: Latest Status and What’s Coming.

Thanks, Matija