docs/platform/migration/migrate-to-encore.md
By building your application with the Encore open-source framework, you unlock powerful features such as the local development tools, automatic infrastructure provisioning, distributed tracing, and service catalog.
The good news: you don't need a complete rewrite. This guide shows you how to adopt Encore incrementally, so you can start benefiting immediately while gradually migrating your existing system.
Incremental migration is more reliable than a complete rewrite. Here's why:
We recommend two approaches:
We've helped 100+ teams adopt Encore and we're happy to answer your questions and provide advice to help you with your migration.
Email us to ask questions, or book a 1:1 call to discuss your specific situation.
Enterprise customers: Encore Cloud can adapt to your unique infrastructure—Kubernetes clusters, VPCs, security policies, and compliance needs—typically within days. Contact us to discuss your requirements.
Migrate services one at a time while your Encore application runs alongside your legacy system, integrated through APIs.
Choose how to deploy your Encore application:
Enterprise: We can adapt to your specific network topology, security policies, and compliance requirements — typically within days. Contact us to discuss your requirements.
Google Cloud example architecture:
Start small and build confidence:
The first step in any project is to create an Encore app. If you've not tried Encore before, we recommend starting by following the Quick Start Guide.
Once you've created you app, integrate it with your GitHub repository and you'll get automatic Preview Environments for every Pull Request.
Since Encore is designed to build distributed systems, it should be straightforward to build a new system that integrates with your existing backend through APIs. See the defining APIs documentation for more details.
Should you want to accept webhooks, that's simple to do using Encore's Raw endpoints.
You can also generate API clients in several languages, which makes it simple to integrate with frontends or other systems. See the Client Generation documentation for more details.
Deploy to Kubernetes
Encore Cloud can deploy directly to your existing Kubernetes cluster:
Contact us to discuss Kubernetes deployment.
Deploy to new Encore-managed infrastructure in your cloud
Connect your AWS or GCP account to deploy in your existing environment:
See infrastructure docs for details.
Your Encore and legacy systems communicate through APIs:
Continue migrating services incrementally. Strategies to consider:
Should you prefer, you can use a forklift migration strategy to move your entire application to Encore in one step by wrapping your existing HTTP router in a catch-all handler.
This strategy works well when:
Benefits:
Limitations:
Here follows a quick summary of the high-level steps of a forklift migration. Find more in-depth instructions in the full forklift migration guide.
To start, create an Encore application and copy over the code from your existing repository. In order to run your application with Encore, it needs to follow the expected application structure, which involves placing the encore.app and package.json files in the repository root. This should be straightforward to do with minor modifications.
As an example, a single service application might look like this on disk:
/my-app
├── package.json
├── encore.app
├── // ... other project files
│
├── encore.service.ts // defines your service root
├── api.ts // API endpoints
├── db.ts // Database definition
You can also have services nested inside a backend folder if you prefer.
Now let's mount your existing HTTP router under a Raw endpoint, which is an Encore API endpoint type that gives you access to the underlying HTTP request.
Here's a basic code example:
import { api } from "encore.dev/api";
export const migrationHandler = api.raw(
{ expose: true, method: "*", path: "/api/*path" },
async (req, resp) => {
// pass request to existing router
}
);
By mounting your existing HTTP router in this way, it will work as a catch-all handler for all HTTP requests and responses. This should make your application deployable through Encore with little refactoring.
Exactly what remains to make your application deployable with Encore will depend on your specific app.
As you run your app locally, using encore run, Encore will parse and compile it, and give you compilation errors to inform what needs to be adjusted.
By iteratively making adjustments, you should relatively quickly be able to get your application up and running with Encore.
Once your application is deployed, gradually break out specific endpoints using Encore's API declarations and introduce infrastructure declarations using the Encore backend frameworks. This incremental refactoring will:
Start with the most frequently modified endpoints or the most critical user flows to maximize the value of refactoring efforts.
Incremental migration lets you adopt Encore without the risk of a complete rewrite.
Service by service migration is the recommended approach—it gives you Encore's full feature set immediately while running safely alongside your existing systems.
Enterprise customers benefit from flexible deployment options, including Kubernetes integration and customization that typically takes just days to set up.
We've helped 100+ teams adopt Encore and we're happy to answer your questions and provide advice to help you with your migration.