Installing Dyrected
Install Dyrected into an existing Next.js App Router project, starting with the Cloud path and keeping the self-hosted path as a separate follow-up option.
Use this page when you are ready to add Dyrected to an existing Next.js app and want the quickest path to a working admin. By the end, you should have Dyrected mounted into your app, know which backend path you chose, and be ready to move on to Defining a Schema.
For this quick start, Dyrected Cloud is the recommended path. It keeps the first setup small: you connect your app, point the admin at your Cloud site, and confirm /admin loads before you start modeling content.
There are two valid setup paths on this page:
- Dyrected Cloud for the fastest quick-start path
- Self-hosted in Next.js if you already know you want the backend inside your own app
If you already know you want the second path, skip straight to Self-hosted in Next.js.
Before you start
Make sure all three of these are true before you run anything:
- your project uses the Next.js App Router
- Node.js 22 or newer is installed
- you are running the command from the root of the Next.js project
The current Next.js integration requires the App Router. The CLI stops with an error if it only finds a Pages Router
project without an app/ directory.
Recommended path: Dyrected Cloud
Choose this path when you want the fastest route to a real editor handoff, do not want to provision your own database and storage first, and want the quick start to feel like a straightforward app integration instead of a backend setup exercise.
Before you run the CLI, open your site in app.dyrected.com and keep these three values nearby:
Site IDSite API keyBase URL
Run the installer
From the root of your Next.js project, run:
npx dyrected init -y -f next -b cloud -p adminThis tells the CLI to target Next.js, use Dyrected Cloud as the backend, and mount the embedded admin at /admin.
The dyrected init command uses:
-y/--yesto accept defaults without prompting-f/--frameworkto targetnextexplicitly-b/--backendto choosecloud-p/--pathto set the admin path
Know what the CLI adds
On the Cloud path, the CLI writes:
dyrected.config.ts
app/admin/page.tsx
instrumentation.ts
.env.exampleIf your app uses src/, the page is written under src/app/ instead.
The important mental model is this: your content model still lives in dyrected.config.ts, but the backend itself stays in Dyrected Cloud.
Fill in the Cloud environment variables
The Cloud scaffold writes these variables into .env.example:
DYRECTED_URLDYRECTED_API_KEYDYRECTED_SITE_IDNEXT_PUBLIC_DYRECTED_URLNEXT_PUBLIC_DYRECTED_API_KEYNEXT_PUBLIC_DYRECTED_SITE_ID
Copy the real values from your Cloud site into .env.
Run the sync script
After the install, run:
npm run dyrected:sync-schemaThe CLI adds this as a script in package.json during setup and also adds a postbuild sync step.
That is there because your schema is still authored in this repo, but Dyrected Cloud needs that schema pushed so the hosted backend knows about your collections, globals, and admin settings.
Do the first boot check
Start your Next.js dev server, open /admin, and create the first admin account.
This is the success signal you care about before changing the schema: the app boots, the admin route loads, and the Cloud-backed admin can sign in.
When to use the self-hosted path instead
Use the self-hosted path when you want the Dyrected backend to run inside your Next.js app from day one, already know your database and storage choices, or want the full backend to stay inside your own deployment boundary.
This is the more advanced path for the quick start. It is valid, but it asks you to think about infrastructure earlier.
Run the self-hosted installer
npx dyrected init -y -f next -b self-hosted -d postgres -s s3 -p adminThis path adds database and storage adapters as part of the install, because the backend will run inside your app.
Know what changes compared to Cloud
Self-hosted Next.js installs still write:
dyrected.config.ts
app/admin/page.tsx
instrumentation.ts
.env.exampleThey also add:
app/dyrected/[...route]/route.tsThat route mounts Dyrected inside your app under /dyrected.
Fill in the local runtime variables
For a self-hosted quick start, the first variables that matter most are:
DATABASE_URLDYRECTED_JWT_SECRETENCRYPTION_KEY
Those are the values that let the backend boot inside your Next.js app.
Do the first boot check
Start your dev server, open /admin, and confirm the app can load the admin with the backend running locally.
On this path, a second useful check is that the route handler exists under app/dyrected/[...route]/route.ts or src/app/dyrected/[...route]/route.ts.
Starter config
Both paths start from the same basic content model. The generated dyrected.config.ts creates:
- a reserved
__adminsauth collection for dashboard users - a
mediaupload collection pagesandpostscollectionsnavigationandsettingsglobals
That starter model is not meant to be your final information architecture. It exists so the admin has something real to show immediately and so the next step, reshaping the schema for your site, starts from working ground instead of a blank file.
Troubleshooting
If something goes wrong, check these first:
- if
/admindoes not load, confirm the admin path you chose duringinit - if Cloud content or login is not working, re-check the values you copied into
.env - if schema changes are not showing up in Cloud, run
npm run dyrected:sync-schema - if the self-hosted path does not boot, re-check
DATABASE_URL,DYRECTED_JWT_SECRET, andENCRYPTION_KEY
For the full troubleshooting guide, see Troubleshooting. That is the right top-level home for deeper error-by-error fixes.
Success check
You are ready for the next page when:
- you know whether this project is Cloud-backed or self-hosted
dyrected.config.tsexists/adminloads- on the self-hosted path, the local route handler exists too
Once those are true, continue to Defining a Schema.
Setting Up Your Cloud Site
Create a Dyrected Cloud site, collect the credentials your Next.js install needs, and choose whether editors will use hosted or embedded admin.
Defining a Schema
Turn the starter Dyrected config into a small, Next.js-friendly schema that matches the pages, shared content, and preview routes your site actually needs.