Encore.ts Tutorial - Build a REST API and serve static files

What is Encore?

Encore is a framework & a development platform for building backend and distributed systems easily. So, why encore you may ask when we already have libraries like Express.js, Bun, & Fastly?

Because it is amazingly Fast

Encore is 9x time faster than express - it can handle 9x more requests per seconds and has 80% less response latency as compared to express.js. You can see the complete comparison Encore vs express, fastify, & bun - blog written by Marcus Kohlberg, where he goes more in depth on why encore is able to do it.

Basically, Encore has 2 parts

1. TypeScript SDK used when writing backend code with encore.ts (encore apps can also be developed in Go or Golang)
2. A Rust high performance runtime with multithreaded, asynchronous event loop.

Encore also has Zero NPM dependencies. Yes, encore doesn't have any dependencies and is built completely from the ground up. This is what the package.json file looks like in a simple encore project:

{
  "name": "encore-ts-starter",
  "private": true,
  "version": "0.0.1",
  "description": "Encore Typescript Starter",
  "license": "MPL-2.0",
  "type": "module",
  "devDependencies": {
    "@types/node": "^20.5.7",
    "typescript": "^5.2.2"
  },
  "dependencies": {
    "encore.dev": "^1.43.8"
  }
}

This allows Encore to run much faster than Express, Bun, and Fastly. You can view more benefits here - Encore Benefits

It is also very easy to create and connect to the Postgres Database with encore (Using SQL databases for backend applications)

---

Get Started with Encore.ts

Let's dive in,

Install the encore cli

• For MacOS you can use brew (Install brew here)

brew install encoredev/tap/encore

• For Windows, you need to open the windows powershell

iwr https://encore.dev/install.ps1 | iex

Create your first Encore Application

First check the installation and encore's version with the command encore version

Note: There is no '-' hyphen before version.

It should show your encore version and if there is another update available. As of writing this blog the latest version is 1.43.12.

Create your first app with the command

encore app create

If this is your first time creating the application, it will ask you to create a free account. Select TypeScript from the options menu (use arrow keys). You will then see a list of templates to choose from, the "Intro to Encore.ts" is a really good starting point which you should opt, for an interactive tutorial. We will be choosing the "Hello World" template which will create a template for a simple REST API. Select a name and hit enter and enter 'Y' to run your first encore app.

This will open up the Development Dashboard and must have the API explorer open. Double click on the :name variable in the string which should allow you to edit it. Hit the "CALL API" button to call it.

You should see the output message:"Hello Viraj!"

You can also check the output on your browser by visiting localhost:4000/hello/Viraj

Understanding the code

There should be a folder created by the name you gave during creating the project. Open the folder in VScode.

You might find that the node_modules folder contains bunch of libraries already. These libraries are used by vitest and its dependencies which is installed with this template (You can create another project and select the empty template which doesn't include the vitest library and you'll see that the node_modules folder doesn't have any libraries other than typescript and encore.dev. This entire template can be made with the empty template, you just need to create the folder 'hello' and add those files in it to get the same result).

In the hello folder open the encore.service.ts file. It should look something like this.

import { Service } from "encore.dev/service";

// Encore will consider this directory and all its subdirectories as part of the "hello" service.\
// https://encore.dev/docs/ts/primitives/services
export default new Service("hello");

This is a way of creating a service in encore. Encore will now consider all the files and directories in this folder as the part of the 'hello' service. This makes creating and managing microservices a piece of cake. Learn more about services and app structure Encore App Structure.

Open the hello.ts file and you can see an api function on the line 15. The api function takes 2 arguments,

1. An object of the type APIOptions which has properties like

1. method?

   Used to define The HTTP method - GET, POST, PUT, etc. Use '*' to handle any method type

2. path?

   The requested path / url

3. expose?

   A boolean which when set to true allows the Api to be publicly accessible. Setting this to false, will only make the Api available for internal components

4. There are 2 other properties `auth?` and `bodyLimit` which we will discuss later

2. A callback function to handle the functionality when the api is called. The callback function is almost similar to express.js call back function except it doesn't get the request and response object, rather, we have to define the request and response type.

We haven't defined any request object here but you can see a Response interface created below the api function. In Encore we have to explicitly mention the types of request and response objects when calling the api function. You can see Promise<Response> mentioned as the return type of the function and the function body returns the object with the name you provided in the request string.

Congratulations, you just created and understood your first REST API in Encore.ts.

---

Deploy your application to the cloud

Encore has built-in integrations with Git and Github. It also includes an automated CI/CD pipeline. Scroll below in the code file to see instructions to deploy you application to cloud.

After completing all the steps, you'll find a link to the remote branch on which your app is deployed Ctrl+Click or Cmd + Click to open the link. It will take a minute to finish building, provisioning, and deploying your code.

Open the 'Other Resources' in the 'Provision Infrastructure'. The app is deployed using the Google Cloud Platform. Now, click on the 'Service Catalog' on the left panel and click on our 'hello' service.

If we add comments on top of the api function in our code and for the request and response objects, encore will create the entire api documentation for us. Copy the link below our API endpoint and paste it in a new browser tab.

You can now share your work with others without setting up and cloud accounts and other routine work. You can also add and deploy the code in your own custom domains which you can find in the 'Overview' tab on the left.

---

Serve Static files in Encore

We just created an api, but how to serve static files with encore?

For this, create another folder, name it whatever you like and create an index.ts file inside the folder. Inside the folder where you created the index.ts file create another folder named 'public' which will include all the static html, css, & javascript files we will need.

Copy the code below into the index.ts file:

import { api } from "encore.dev/api";

import path from "path";
import { readFileSync } from "fs";

const filePath = path.join(process.cwd(), "frontend", "public", "html", "index.html")
const htmlFile = readFileSync(filePath, "utf-8");

//raw endpoint
export const serveStatic = api.raw(
  { expose: true, method: "GET", path: "/frontend" },
  async (req, res) => {
    res.setHeader("Content-Type", "text/html");
    res.end(htmlFile);
  }
);

export const staticAssets = api.static({
  expose: true,
  path: "/*path",
  dir: "./public",
});

Note: I have named the folder 'frontend' change the name to whatever your folder name is.

You will see we have used api.raw method instead of the standard api method which provides access to the HTTP request and response objects. This is useful when you need to operate at a lower level of abstraction than what Encore.ts normally provides, such as handling webhooks or other custom HTTP interactions.

Note: We don't have direct access to the __dirname variable which was available when using the CommonJS modules. Hence, 'fs' and 'path' libraries are imported as a work around.

The callback function works the same as we would define it in a basic node.js server.

The api.static method is used to serve static files. This method takes in a different APIOptions property called "dir" which points to the directory where all the static files are.

---

Conclusion

Encore is a really powerful framework which is still fairly new but there are constant updates from the creators every month. Being fast and using no libraries as compared to other frameworks like React is surely a huge benefit when it comes to modern applications.

Follow me on my socials to get updates on my latest blogs and tutorials.

X: @VirajDoshi72

Linkedin: virajdoshi7

Visit my website: https://virajdoshi.xyz/