Build a Type-Safe Web App with Encore + Next.js
Tags: nextjs, programming, go, typescript
Published: 2023-10-13 14:45:25

This is a quick guide to creating and deploying an [Encore](https://encore.dev/) + [Next.js](https://nextjs.org/) web app.

🌟 It's a great way to learn how to combine Encore's backend capabilities with a modern web framework, so you can build a more robust and production-ready web app.

Let's go! 🚀

## Setup your local dev environment

### Install Encore

If this is the first time you're using Encore, you first need to install the CLI that runs the local environment. Use the appropriate command for your system:
- **macOS:** `brew install encoredev/tap/encore`
- **Linux:** `curl -L https://encore.dev/install.sh | bash`
- **Windows:** `iwr https://encore.dev/install.ps1 | iex`

### Create app

When you have [installed Encore](https://encore.dev/docs/install), create a new Encore application and clone this example:

```bash
encore app create my-app --example=nextjs-starter
```

### Running locally

Run your Encore backend:
```bash
encore run
```

In a different terminal window, run the Next.js frontend:
```bash
cd frontend
npm install
npm run dev
```

👉 Open [http://localhost:3000](http://localhost:3000) in your browser to see the result.


![Web app template](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/f5gu5s1f0936hrbhq9vr.png)

### Encore's Local Development Dashboard

While `encore run` is running, open <http://localhost:9400/> to view Encore's local developer dashboard. Here you can see the request you just made and view a trace of the response.


![Encore local dev dashboard](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/1brerbowy62l8f2fag0q.png)

### 🤝 Generate a request client and stay type-safe

Keep the contract between the backend and frontend in sync by regenerating the request client whenever you make a change to an Encore endpoint.

```bash
npm run gen # Deployed Encore staging environment
# or
npm run gen:local # Locally running Encore backend
```

## 🚀 Deploy to the cloud

### Encore

Deploy your backend to a staging environment in Encore's free development cloud:

```bash
git add -A .
git commit -m 'Initial commit'
git push encore
```

👉 Then head over to the [Cloud Dashboard](https://app.encore.dev) to monitor your deployment and find your production URL.

From there you can also see metrics, traces, connect your app to a GitHub repo to get automatic deploys on new commits, and connect your own AWS or GCP account to use for deployment.

![Encore Cloud Dashboard](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/7kmyqylyk7lxvuvosl4k.png)

### Next.js on Vercel

1. Create a repo and push the project to GitHub
2. Create a new project on Vercel and point it to your GitHup repo
3. Select `frontend` as the root directory for the Vercel project

### 🚀 Great job - you're done!

You now have a scalable and production-ready web app foundation running in the cloud. 🎉

Now keep building!

If you have questions or want to share your work, join the developers hangout in [Encore's community Slack](https://encore.dev/slack). 👈

## CORS configuration

If you are running into CORS issues when calling your Encore API from your frontend then you may need to specify which origins are allowed to access your API (via browsers). You do this by specifying the `global_cors` key in the `encore.app` file, which has the following structure:

```jsonc
global_cors: {
  // allow_origins_without_credentials specifies the allowed origins for requests
  // that don't include credentials. If nil it defaults to allowing all domains
  // (equivalent to ["*"]).
  "allow_origins_without_credentials": [
    "<ORIGIN-GOES-HERE>"
  ],
        
  // allow_origins_with_credentials specifies the allowed origins for requests
  // that include credentials. If a request is made from an Origin in this list
  // Encore responds with Access-Control-Allow-Origin: <Origin>.
  //
  // The URLs in this list may include wildcards (e.g. "https://*.example.com"
  // or "https://*-myapp.example.com").
  "allow_origins_with_credentials": [
    "<DOMAIN-GOES-HERE>"
  ]
}
```

More information on CORS configuration can be found here: https://encore.dev/docs/develop/cors

## Learn More

- [Encore Documentation](https://encore.dev/docs)
- [Next.js Documentation](https://nextjs.org/docs)