DyadPortal template (experimental)
Portal template shows Neon DB, Payload CMS and Next.js working together in a simple online store.
The Portal template is available as experimental in v0.16.0 Beta. It's not yet ready for production-usage, but please report any bugs and we'll fix them.
Overview
The Portal template is designed for business use cases—especially where you have multiple user roles (e.g. customers and employees) that require distinct permissions and interfaces.
What it's good for
- Business applications – If you're building an app for customers or employees, start here. The Portal template offers much more out of the box than our minimal templates.
- Complex access control – It’s easy to support different roles and permissions for different data and UIs. For example, customers can view their orders, while employees access a full admin panel. Payload handles this gracefully by auto-generating the admin panel from your schema.
What it's not good for
- One-off prototypes – The Portal template requires a non-trivial setup and deployment process (as you can probably tell from the length of this doc!). If you're just making a quick demo, this may be overkill—though still usable.
- Mobile apps – Since it’s based on Next.js, the Portal template isn’t ideal for mobile apps. If you're building one, use the default React template instead.
How it works
The Portal template combines several technologies in a cohesive, easy-to-use setup:
- Neon DB is a serverless Postgres service with standout features like branching and time-travel restore. You can "undo" database changes just like you would with code, and easily manage development and production branches.
- Payload CMS is a modern, headless content management system. Think of it like a more flexible, extensible WordPress—built on a modern stack. It integrates seamlessly with Next.js, allowing you to host both the admin panel and customer-facing site on a single server (e.g. Vercel).
- Next.js is a full-stack React framework developed by Vercel. It enables seamless front-end and back-end integration and offers a suite of performance optimizations, especially when deployed on Vercel.
You don’t need to be an expert in these technologies to get started, but as your app evolves, becoming familiar with them will help you debug and deploy more effectively.
Development
Set up Neon DB
Start by going to the Hub tab and setting up the Neon backend provider. You can connect an existing Neon account or create a new one—Neon has a generous free tier.
Use the Portal template
From the Hub, select the Portal: Mini Store template and create your app. This will automatically create a Neon project and link it with your app.
Make sure it works
Since the Portal template involves multiple components, verify that everything works on your machine before making changes. Start by creating an admin user—click the Admin Portal link at the bottom of the page.
The first load of the Portal template can take a while. Don’t worry—subsequent loads will be much faster.
Now you're ready to start customizing your Portal app.
Database management
As mentioned earlier, Neon DB has a few standout features that make it excellent for AI-powered development.
Undo / restore
Neon allows you to restore your database to any point within the last 24 hours (on the free tier). You can have a longer restore window if you upgrade to a paid plan.
If you made a mistake in Dyad, just click Undo and your database will revert to its previous state. You can also use the Versions list to restore to an earlier version.
Important: Once you restore to an earlier version, you permanently lose access to all database states that existed after that restore point. However, you can continue creating new restore points from your current version going forward.
Email setup
If you want to support Forgot password and other functionality which requires email, you'll need to set up email. We recommend doing this, otherwise it's easy for users to get locked out of their account if they forget their password.
The easiest and cheapest way to setup email is to use Gmail which lets you send ~500 emails per day with a free account.
Gmail isn't designed for large-volume email sending and the limit can vary and change. If you need a production-grade email sending service, you can use Resend which has a Payload integration
Create a new gmail account
We recommend creating a new gmail account like [email protected] so that if you hit your sending limit, it doesn't affect your main Google account.
Setup two-factor authentication
You will need to setup two-factor authentication for your new Google account to do the next step.
Create app password
Create an app password for your Google account. An app password gives full access to your Google account, so keep it safe!
If you have trouble creating your app password, read Google's guide.
Configure environment variable
Inside your app in Dyad, go to the Configure panel and update the following environment variables:
GMAIL_USER- configure it to your new Google account (e.g. [email protected])GOOGLE_APP_PASSWORD- paste in the app password that you created in the previous step. This is not your regular Google password.
Once you've finished setting it up, try using the Forgot password flow and make sure you can receive the email.
Production
When you're ready to launch your Portal app, you can follow one of these setups:
- Shared database across environments
- Separate database per environment (recommended for production apps)
Shared database across environments
This setup is only recommended for prototype apps. If you are building a production app, follow the other setup: Seeparate database per environment
Sync to GitHub
If you haven’t already, create a GitHub repo and sync your app. See the publishing guide for details.
Create a Vercel project
This is similar to the steps in the publishing guide, but with a couple key environment variables:
POSTGRES_URL– copy this from your Environment Variables in the Configure panel.PAYLOAD_SECRET– copy this from your Environment Variables in the Configure panel. This must be exactly the same since you're sharing the database between development and production
Check you can login as admin user
Since you should have already created an admin user during development and you're sharing the same database, log in to the admin panel (e.g. your-site.vercel.app/admin) and make sure it works.
Separate database per environment
If you are building a production app, we highly recommend following this setup.
First-time deployment
Click the Deploy button (top-right) to open the Deployment pane and follow these steps:
Setup your Neon production project
Inside the Neon Console, create a new project, which will contain your production database.
Sync to GitHub
If you haven’t already, create a GitHub repo and sync your app. See the publishing guide for details.
Create a Vercel project
This is similar to the steps in the publishing guide, but with a couple of key environment variables:
POSTGRES_URL– Inside Neon Console, navigate to your project > Branches and click on the "main" branch. Click on Connect and copy the database connection URL.PAYLOAD_SECRET– Generate a random string. Don’t change it after setting it in Vercel, or your app will break. You can look at this environment variable in the Configure panel to see what a random string should look like, but we recommend not using the exact same random string for both development and production.
Create your admin user
Because the production database starts empty, you'll need to create the admin user immediately—before someone else does.
Congrats—you’ve deployed your app to production! Be sure to check that everything works as expected, since subtle differences can arise between environments. Then, go share your app with the world!
Ongoing deployment
After launch, it’s wise to be more cautious with database changes. You can update your AI rules to be production-safe. The main thing you need to do now is to Create a database migration before you push to GitHub.
Create a database migration
From now on, before you push changes to GitHub, you should create a database migration. On the Publish panel, you'll see a box called Portal Database Migration, click on the Generate database migration before you push changes to GitHub. This will create a migration file if it's needed.
Not sure what a database migration is? It's basically a set of instructions that tells your database how to update from one version of the schema to the next version while migrating all the existing data. When you deploy your app on Vercel, the build runner on Vercel will read the migration file and apply the changes to your production database
Push to GitHub and monitor Vercel
Sync to GitHub. This triggers a Vercel deployment. Head to your Vercel dashboard and confirm the build completed successfully.
After each deployment, it’s a good habit to manually test the app. If something goes wrong, you can roll back to a previous deployment in Vercel and use Neon's instant restore to revert the database.