{"id":15100,"library":"encore.dev","title":"Encore JavaScript/TypeScript SDK","description":"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.","status":"active","version":"1.56.6","language":"javascript","source_language":"en","source_url":"https://github.com/encoredev/encore","tags":["javascript"],"install":[{"cmd":"npm install encore.dev","lang":"bash","label":"npm"},{"cmd":"yarn add encore.dev","lang":"bash","label":"yarn"},{"cmd":"pnpm add encore.dev","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Requires a compatible Node.js runtime for execution.","package":"node","optional":false}],"imports":[{"note":"Use named imports for defining Encore API services. The SDK is primarily designed for modern JavaScript/TypeScript (ESM) environments.","wrong":"const { api } = require('encore.dev');","symbol":"api","correct":"import { api } from 'encore.dev';"},{"note":"The `Cache` object and its associated Keyspace types (e.g., `StringKeyspace`) are named exports. Introduced in v1.55.0 for type-safe caching.","wrong":"import Cache from 'encore.dev';","symbol":"Cache","correct":"import { Cache } from 'encore.dev';"},{"note":"Used for defining authentication mechanisms for Encore services. Like other core SDK components, it's a named export.","wrong":"const { Auth } = require('encore.dev');","symbol":"Auth","correct":"import { Auth } from 'encore.dev';"}],"quickstart":{"code":"import { api, Cache, StringKeyspace } from 'encore.dev';\n\n// Define a type for user data that will be cached\ninterface UserData {\n  id: string;\n  name: string;\n  email: string;\n}\n\n// Declare a type-safe cache keyspace for user data\nconst userCache = Cache.declare(\n  'user_data',\n  StringKeyspace<UserData>() // Keys are strings, values are UserData objects\n);\n\n// Define an Encore service named 'UserService'\n// This service exposes a GET /user/:id API endpoint\nexport const user = api(\n  {\n    name: 'UserService',\n    endpoint: 'user',\n    path: '/user/:id',\n    method: 'GET',\n  },\n  async (id: string): Promise<UserData> => {\n    // Try to retrieve user data from the cache first\n    const cachedUser = await userCache.get(id);\n    if (cachedUser) {\n      console.log(`[Encore] User ${id} found in cache.`);\n      return cachedUser;\n    }\n\n    // If not in cache, simulate fetching from a 'database'\n    console.log(`[Encore] Fetching user ${id} from database...`);\n    await new Promise(resolve => setTimeout(resolve, 200)); // Simulate async DB call\n\n    const userData: UserData = { \n      id: id, \n      name: `User ${id} Name`, \n      email: `user${id}@example.com` \n    };\n\n    // Store the fetched data in the cache for 5 minutes (300 seconds)\n    await userCache.put(id, userData, { ttl: 300 });\n\n    return userData;\n  }\n);\n\n// To run this, save as user.ts in an Encore application directory\n// and execute 'encore run'. The API endpoint will be exposed automatically.","lang":"typescript","description":"Demonstrates defining an Encore API service in TypeScript with type-safe caching using a `StringKeyspace` to retrieve and store user data."},"warnings":[{"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.","message":"The SDK requires Node.js version 18.0.0 or higher. Running with older versions may lead to unexpected errors or incompatible syntax.","severity":"gotcha","affected_versions":"<1.0.0"},{"fix":"Install the Encore CLI (`curl -L https://encore.dev/install | bash`) and initialize an Encore application to use the SDK as intended.","message":"This 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Update your scripts and practices to use `encore secret delete` for removing secrets, allowing for reuse of secret names after deletion.","message":"The `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.","severity":"deprecated","affected_versions":">=1.56.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Use ES module `import` statements instead: `import { someSymbol } from 'encore.dev';`","cause":"Attempting to use CommonJS `require()` syntax in an ES Module (ESM) context, which is the default for modern TypeScript/JavaScript projects using `encore.dev`.","error":"ReferenceError: require is not defined in ES module scope"},{"fix":"Run your Encore application using the `encore run` command from your terminal, or deploy it with `encore deploy`.","cause":"Attempting to execute an Encore service file directly with `node` or `ts-node` without the Encore runtime context.","error":"Error: Encore services must be run within the Encore development environment or deployed."},{"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.","cause":"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.","error":"TypeError: Cannot read properties of undefined (reading 'get') or 'api' is not a function"}],"ecosystem":"npm"}