Encore JavaScript/TypeScript SDK

Common errors

• ReferenceError: require is not defined in ES module scope

  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`.
  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.

  cause 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

  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.
  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.

Warnings

• gotcha The 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.
• gotcha 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.
  Fix: Install the Encore CLI (`curl -L https://encore.dev/install | bash`) and initialize an Encore application to use the SDK as intended.
• deprecated 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.
  Fix: Update your scripts and practices to use `encore secret delete` for removing secrets, allowing for reuse of secret names after deletion.

Install

• npm install encore.dev npm
• yarn add encore.dev yarn
• pnpm add encore.dev pnpm

Imports

• api
  wrong:

  const { api } = require('encore.dev');

  correct:

  import { api } from 'encore.dev';

  Use named imports for defining Encore API services. The SDK is primarily designed for modern JavaScript/TypeScript (ESM) environments.
• Cache
  wrong:

  import Cache from 'encore.dev';

  correct:

  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
  wrong:

  const { Auth } = require('encore.dev');

  correct:

  import { Auth } from 'encore.dev';

  Used for defining authentication mechanisms for Encore services. Like other core SDK components, it's a named export.

Quickstart

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.