Registry / web-framework / encore.dev

encore.dev

JSON →
library1.56.6jsnpmunverified

Encore's JavaScript/TypeScript SDK, currently at stable version 1.56.6, provides the necessary APIs and development utilities for building backend applications within the Encore cloud platform. It enables developers to define services, interact with built-in platform features like caching and secrets, and manage application infrastructure using a declarative, type-safe approach. The SDK integrates seamlessly with the Encore CLI and platform, abstracting away complex infrastructure provisioning. Recent updates include comprehensive built-in support for caching in Encore.ts, powered by Redis, offering various type-safe keyspace types such as `StringKeyspace` and `StructKeyspace`. It also includes internal improvements for Go 1.26 support and enhanced secret management features via the CLI. Releases are frequent, typically focusing on minor fixes, performance enhancements, and new platform feature integrations.

npm install encore.dev
INSTALL
IMPORT
SIG · ENCORE.DEV
E
encore.dev
web-frameworkjavascriptv1.56.6
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

api
✓ import { api } from 'encore.dev';
✗ const { api } = require('encore.dev');
Use named imports for defining Encore API services. The SDK is primarily designed for modern JavaScript/TypeScript (ESM) environments.
Cache
✓ import { Cache } from 'encore.dev';
✗ import Cache from 'encore.dev';
The `Cache` object and its associated Keyspace types (e.g., `StringKeyspace`) are named exports. Introduced in v1.55.0 for type-safe caching.
Auth
✓ import { Auth } from 'encore.dev';
✗ const { Auth } = require('encore.dev');
Used for defining authentication mechanisms for Encore services. Like other core SDK components, it's a named export.

Demonstrates defining an Encore API service in TypeScript with type-safe caching using a `StringKeyspace` to retrieve and store user data.

import { api, Cache, StringKeyspace } from 'encore.dev'; // Define a type for user data that will be cached interface UserData { id: string; name: string; email: string; } // Declare a type-safe cache keyspace for user data const userCache = Cache.declare( 'user_data', StringKeyspace<UserData>() // Keys are strings, values are UserData objects ); // Define an Encore service named 'UserService' // This service exposes a GET /user/:id API endpoint export const user = api( { name: 'UserService', endpoint: 'user', path: '/user/:id', method: 'GET', }, async (id: string): Promise<UserData> => { // Try to retrieve user data from the cache first const cachedUser = await userCache.get(id); if (cachedUser) { console.log(`[Encore] User ${id} found in cache.`); return cachedUser; } // If not in cache, simulate fetching from a 'database' console.log(`[Encore] Fetching user ${id} from database...`); await new Promise(resolve => setTimeout(resolve, 200)); // Simulate async DB call const userData: UserData = { id: id, name: `User ${id} Name`, email: `user${id}@example.com` }; // Store the fetched data in the cache for 5 minutes (300 seconds) await userCache.put(id, userData, { ttl: 300 }); return userData; } ); // To run this, save as user.ts in an Encore application directory // and execute 'encore run'. The API endpoint will be exposed automatically.
encore --version
Debug
Known issues
gotchaThe SDK requires Node.js version 18.0.0 or higher. Running with older versions may lead to unexpected errors or incompatible syntax.
fix
Ensure your Node.js environment is updated to version 18.0.0 or later. Use `nvm` or similar tools for managing Node.js versions.
affects: <1.0.0
gotchaThis package is an SDK for the Encore platform and is not a standalone library. It requires the Encore CLI and development environment or a deployed Encore application to function correctly.
fix
Install the Encore CLI (`curl -L https://encore.dev/install | bash`) and initialize an Encore application to use the SDK as intended.
affects: >=1.0.0
deprecatedThe `encore secret archive` and `encore secret unarchive` CLI commands have been deprecated in favor of `encore secret delete`. While this primarily affects the CLI, it impacts the overall secret management workflow.
fix
Update your scripts and practices to use `encore secret delete` for removing secrets, allowing for reuse of secret names after deletion.
affects: >=1.56.0
Errors
Common errors & fixes
ReferenceError: require is not defined in ES module scope
Attempting to use CommonJS `require()` syntax in an ES Module (ESM) context, which is the default for modern TypeScript/JavaScript projects using `encore.dev`.
fix
Use ES module `import` statements instead: `import { someSymbol } from 'encore.dev';`
Error: Encore services must be run within the Encore development environment or deployed.
Attempting to execute an Encore service file directly with `node` or `ts-node` without the Encore runtime context.
fix
Run your Encore application using the `encore run` command from your terminal, or deploy it with `encore deploy`.
TypeError: Cannot read properties of undefined (reading 'get') or 'api' is not a function
This usually indicates that the `encore.dev` module was not correctly imported, or the Encore runtime environment is not active, leading to undefined SDK objects.
fix
Verify that `import { api, Cache } from 'encore.dev';` is at the top of your file and ensure your application is launched via `encore run` or deployed to the Encore platform.
Upgrade
Version history
1.56.6latest on npm
Audit
Dependencies
noderequiredRequires a compatible Node.js runtime for execution.
Agent activity
20 hits · last 30 days
node
18
OpenAI (training)
2
Resources
encore.dev — npm install encore.dev · libregistry