Coming from Heroku

Heroku organizes an application around process types, dynos, config vars, and add-ons. Encore instead derives an application model from the APIs, services, and infrastructure declared with its TypeScript or Go SDK. The model describes the backend's structure and resource relationships rather than commands for runtime process types.

How the concepts map

Heroku	Encore
App and pipeline stage	Encore application and environment
web process type	Encore API endpoints, grouped into services
Worker dyno	Pub/Sub subscription, cron endpoint, or an externally operated worker
Dyno formation and size	Environment compute configuration
Heroku Postgres	SQL database
Heroku Key-Value Store	Cache for supported cache use cases, or an external Redis- or Valkey-compatible store
Config vars	Secrets, constants, or external configuration
Scheduler	Cron jobs
Add-on	Encore primitive, application code, or external dependency
Review app	Preview environment

These primitives are declared in application code using TypeScript or Go.

An Encore service is a code and API boundary, not a dyno process type. Encore deploys the application from its service and resource graph; it does not read a Procfile or preserve a dyno formation.

Migrate web and worker processes

Define routes from a Heroku web process as Encore API endpoints. Existing TypeScript or Go application logic can remain behind those endpoints. A catch-all endpoint can wrap an existing router during an incremental migration; see Migrating an existing system.

Classify each non-web process by what triggers it:

• Use Pub/Sub for event-driven background work.
• Use cron jobs for scheduled calls to API endpoints.
• Keep an external worker when it requires an indefinite process, a protocol, or runtime behavior not represented by Encore.

• Use Pub/Sub for event-driven background work.
• Use cron jobs for scheduled calls to API endpoints.
• Keep an external worker when it requires an indefinite process, a protocol, or runtime behavior not represented by Encore.

Release-phase commands and one-off dynos have no general one-to-one mapping. Database migrations declared for an Encore SQL database run as part of deployment. Handle other administrative jobs through CI, a protected API endpoint, or an external operational process.

Migrate databases, Key-Value Store, and add-ons

Heroku Postgres cannot be imported directly into Encore Cloud. Provision a target Postgres database and transfer the schema and data. Review extensions, ownership, roles, version compatibility, and the write cutover. For self-hosting, an infra config can connect an Encore database declaration to a compatible existing server.

Encore's cache primitive does not expose the full Redis or Valkey API. Check the application's commands, persistence assumptions, and eviction behavior before replacing Heroku Key-Value Store. Applications that require the general-purpose API can continue using it as an external dependency.

Treat each add-on as a separate migration. Replace it with an Encore primitive where there is a functional match, implement the capability in application code, move to another provider, or retain the add-on while Heroku permits access from the new environment. Check network allowlists and add-on attachment or billing rules before assuming it can be used outside the Heroku app.

Move credentials from config vars to Encore secrets. Non-secret config vars do not have a direct equivalent: use constants for invariant values or an external configuration service for runtime configuration.

Deployments, domains, and cutover

Encore can deploy on pushes from a connected GitHub repository and create per-PR preview environments on supported plans. Heroku pipeline promotion, build configuration (classic buildpacks and slugs on Cedar, Cloud Native Buildpacks and OCI images on Fir), and app.json setup are not transferred; reproduce required build or release work in Encore or CI.

Set up the Encore environment and verify its generated API URL first. Then add the existing hostname as an Encore custom domain and update DNS. Keep the Heroku app available until traffic and background work have been verified. If the application shares a database during the transition, both versions must be compatible with the active schema.

Migration plan

1. Inventory process types, dyno formation, config vars, add-ons, domains, and scheduled jobs.
2. Move one stateless web process or bounded route group into Encore.
3. Convert workers according to their trigger and delivery requirements.
4. Migrate add-ons independently; do not treat the marketplace as one unit.
5. Transfer database data and rehearse the final write cutover.
6. Shift traffic, monitor the Encore deployment, and then scale down the replaced dynos.

For shared PaaS migration guidance, see Coming from a PaaS. Heroku behavior referenced here is documented in The Procfile, Config Vars, Heroku Postgres, Heroku Key-Value Store, and Review Apps.