This is an example of how to do user authentication using Clerk together with an Encore app. Check out the Use Clerk with your app guide to learn more about this example.
If this is the first time you're using Encore, you first need to install the CLI that runs the local development 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
When you have installed Encore, run to clone this example:
encore app create my-app --example=ts/clerk
-
Create a Clerk account if you haven't already. Then, in the Clerk dashboard, create a new application.
-
Go to the API Keys page for your app. Copy the "Publishable Key" and one of the "Secret keys".
-
In
frontend/.env
file, replace the values forVITE_CLERK_PUBLISHABLE_KEY
with the value from your Clerk dashboard. -
The
Secret key
is sensitive and should not be hardcoded in your code/config. Instead, you should store that as an Encore secret.
From your terminal (inside your Encore app directory), run:
$ encore secret set --prod ClerkSecretKey
- Do the same for the development secret. The most secure way is to create another secret key (Clerk allows you to have multiple). Once you have a client secret for development, set it similarly to before:
$ encore secret set --dev ClerkSecretKey
- Go the Domains page for your app in the Clerk dashboard. There you will find the domain for your app. Replace the value for the
DOMAIN
variable inauth/config.ts
with your domain.
Run your Encore backend:
encore run
In a different terminal window, run the React frontend using Vite:
cd frontend
npm run dev
Open http://localhost:5173 in your browser to see the result.
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 a view a trace of the response.
Keep the contract between the backend and frontend in sync by regenerating the request client whenever you make a change to an Encore endpoint.
npm run gen # Locally running Encore backend
See the self-hosting instructions for how to use encore build docker
to create a Docker image and configure it.
Deploy your application to a free staging environment in Encore's development cloud using git push encore
:
git add -A .
git commit -m 'Commit message'
git push encore
You can also open your app in the Cloud Dashboard to integrate with GitHub, or connect your AWS/GCP account, enabling Encore to automatically handle cloud deployments for you.
Follow these steps to link your app to GitHub:
- Create a GitHub repo, commit and push the app.
- Open your app in the Cloud Dashboard.
- Go to Settings ➔ GitHub and click on Link app to GitHub to link your app to GitHub and select the repo you just created.
- To configure Encore to automatically trigger deploys when you push to a specific branch name, go to the Overview page for your intended environment. Click on Settings and then in the section Branch Push configure the Branch name and hit Save.
- Commit and push a change to GitHub to trigger a deploy.
The frontend can be deployed to Vercel. Follow these steps:
- Create a repo and push the project to GitHub.
- Create a new project on Vercel and point it to your GitHup repo.
- Select
frontend
as the root directory for the Vercel project.
Once you have your frontend deployed:
- Update the
AUTHORIZED_PARTIES
array inauth/config.ts
to include the deployed Vercel URL. - Set the
allow_origins_with_credentials
in theencore.app
(see below) file to the deployed Vercel URL.
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:
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/ts/develop/cors