Skip to main content
The Next.js quickstart walks you through your first deployment to Laravel Cloud. Since Cloud already knows how to build and start a Next.js application, this guide focuses on the handful of things that are still yours to decide, such as how your environment variables reach the browser, where your data lives, and how your database is migrated. Each section links to the full documentation if you would like to dig deeper.

​
Choose a runtime version

Cloud can run your Next.js application on Node.js, Bun, or Deno, and it detects the right runtime from the files in your repository. A package-lock.json file selects Node.js, a bun.lock, bun.lockb, or bunfig.toml file selects Bun, and a deno.json or deno.lock file selects Deno. If you are using Node.js, you may choose your version from the Runtime section of your environment’s General Settings page. After changing it, redeploy your environment so the new version takes effect. Bun and Deno run on a fixed version, so there’s nothing to choose. You can find the supported versions in the Runtimes documentation.

​
Build your application

Your environment’s build commands run each time you deploy. Typically, they will install your dependencies and compile your application:
If you prefer Yarn, pnpm, or Bun over npm, take a look at Using Yarn, PNPM, or Bun.

​
Start your application

Cloud starts your application by running the start script defined in your package.json file, which is usually next start. If you are using the Deno runtime, Cloud runs deno task start instead. You may override the start command from your environment’s deployment settings if needed. Cloud routes traffic to your application on the port set by the PORT environment variable. The next start command reads this variable automatically, so most applications work without any changes. However, if you have replaced next start with a custom server, such as an Express server in a server.js file, make sure that server reads PORT rather than listening on a hardcoded port. Otherwise, your deployment will succeed but won’t receive any traffic. The deployment troubleshooting guide has more details.

​
Environment variables

You may add your environment variables from your environment’s settings. Cloud sets them directly on your application’s process, so your server code can read them from process.env just like it does locally. Variables prefixed with NEXT_PUBLIC_ are also available in the browser, while all other variables stay on the server. Keep in mind that Next.js inlines NEXT_PUBLIC_ values into your JavaScript when your application is built. Your build commands receive your environment variables through a .env file, so these values are available during the build, but you will need to redeploy whenever you change one so the new value is compiled into your application. In addition to your own variables, Cloud automatically sets NODE_ENV=production and NEXT_PUBLIC_SITE_URL, which contains your application’s URL, on every deployment.

​
Attach a database or cache

When you attach a database or cache from your environment’s infrastructure canvas, Cloud injects a DATABASE_URL or REDIS_URL connection string into your environment. Most database libraries and ORMs, including Prisma and Drizzle, accept these URLs directly. The Node.js deploy guide includes examples for several popular clients. Your environment’s filesystem is reset each time you deploy, and each replica of your application has its own disk. Because of this, anything your application needs to share or keep, such as sessions or cached data, should live in an attached database or cache rather than on disk. The same applies to Next.js’s own data cache and incremental static regeneration. By default, Next.js stores these on the local filesystem, so each replica keeps its own copy and the cache is cleared on every deployment. If your application relies on revalidated pages staying consistent across replicas, configure a custom cache handler backed by your cache.

​
Store files in object storage

For user uploads and any other files your application needs to keep, attach a bucket to your environment as its default disk. Cloud injects the AWS_BUCKET, AWS_ENDPOINT_URL, AWS_REGION, AWS_ACCESS_KEY_ID, and AWS_SECRET_ACCESS_KEY variables. When creating your S3 client with the AWS SDK for JavaScript, be sure to pass the endpoint explicitly:

​
Run migrations

Database migrations belong in your environment’s deploy commands. Cloud runs these commands just before your new deployment goes live. If one of them fails, Cloud cancels the rollout. For example, if you are using Prisma, your deploy command might look like this:
Keep in mind that deploy commands must finish within 15 minutes, and any changes they make to the filesystem will not be kept.