v1.39: Encore.ts Bonanza!

[eandre]

We're excited to announce a new release of Encore.ts, which includes a ton of improvements and bug-fixes. As always, get it with encore version update.

Encore.ts: Explicit service roots (#1274)

One thing a lot of newcomers to Encore struggled with was the implicit way that you defined services: by having a folder that contains at least one API endpoint. It led to a lot of confusion around how to define services and how to best organize the code.

To fix this, we've introduced a new, much more explicit way of defining services. Starting with this release you can define a service by creating a file named encore.service.ts containing:

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

export default new Service("service-name", {});

Encore will consider the folder it lives in as the "service root", and everything within it (including subdirectories) is part of the service.

The second argument ({} in the example above) is an optional config object. Currently there are no additional options for a service, but we'll be adding some in the near future.

The old approach will continue to work. We recommend all Encore.ts users start using this going forward, and we'll provide a way to opt-in to enforcing this for those who want it. We're updating all examples to use this approach.

For Encore.go users: This functionality is also coming to Encore.go! It's a slightly larger undertaking due to some design differences between Encore.ts and Encore.go.

Encore.ts: Logs in traces (#1248)

Log messages written using Encore's structured logging package (encore.dev/log) are now automatically included in traces.

This package also automatically adds useful metadata to each log line (including things like which request is being processed, the service and endpoint being called, trace and span information, and more).

We recommend using encore.dev/log for all your logging needs!

Encore.ts: Body size limits (#1268)

You can now configure the maximum request body size for any Encore API endpoint:

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

// Limit the body to 10 MiB.
export const myEndpoint = api({ bodyLimit: 10 * 1024 * 1024 },
  async (req: Params) => Promise<void> {
    // ...
  }
);

You can also set bodyLimit: null to remove the limit altogether. If you leave it unset, it defaults to 2MiB.

Encore.ts: Support for enum types (#1254)

You can now use TypeScript enums in your API schemas! That means this is possible:

enum PostType {
  BlogPost = "BLOG_POST",
  Comment = "COMMENT"
}

interface PublishParams {
  type: PostType,
  // ... more fields
}

export const publish = api(
  { expose: true, method: "POST", path: "/publish" },
  async (params: PublishParams) => Promise<Post> {
    // ...
  }
);

Encore interprets this like type: "BLOG_POST" | "COMMENT".

Encore.ts: Number literal math expressions (#1271)

As seen in the body size example snippet above, you can now use common mathematical operators like +-*/% in configuration that Encore parses with static analysis. This makes certain numbers much easier to express (like 10MiB above).

Encore.ts: Literal null support (#1236)

You can now use null in Encore API schemas (including in unions: foo: string | null).

Union types in OpenAPI generation (#1257)

Encore's OpenAPI generator now correctly handles TypeScript union types.

Bugfixes & Other Improvements

• TS: Pub/Sub subscriptions are now always initialized even if not otherwise imported (#1276)
• TS: Randomize the port for the Rust runtime's SQL database proxy (#1266)
• TS: URL-encode API call parameters (#1262)
• TS: Support more complex types in path parameters (#1261)
• TS: Parse JSDoc comments correctly (#1258)
• TS: Improved runtime logging (#1249)
• TS: Fix stripping of path params from request payload (#1252)
• TS: Support gzipped env data (#1255)
• TS: Handle unary plus and minus (#1256)
• ... And lots more!

Thanks to all contributors

🙏 We continue to be overwhelmed by your support, feedback, and suggestions!
Together we're building the future of backend development and we couldn't be more excited.

❤️ As always, we're excited to hear what you think!
Please share your feedback on Discord.

---

This discussion was created from the release v1.39: Encore.ts Bonanza!.