> For the complete documentation index, see [llms.txt](https://docs.thewalletcrew.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.thewalletcrew.io/developers-guides/scripting/how-scripts-run.md).

# How scripts run

How The Wallet Crew finds, loads and registers script files, what an error in one file does to the others, and what is validated when you save.

Behind every scripting problem there is a rule about how files are found, loaded and registered. A script that "does nothing" usually was never loaded, was loaded but registered under another key, or was shadowed by a second file registering the same key; a script that "breaks everything" has an error that the platform reports for the whole tenant.

## Which files are loaded

Every file under `server/scripts/` in the tenant configuration is considered, subfolders included. A file is a script when its name ends with `.js`, in lowercase: `crm.js` and `lookups/crm.js` are scripts, `crm.JS` and `crm.js.bak` are not and are ignored without any message. Files outside `server/scripts/` are never loaded as scripts, even when they contain JavaScript.

Scripts cannot import each other: there are no relative imports. A file may import only the platform modules, such as `twc/secrets` (see [Modules](https://docs.thewalletcrew.io/developers-guides/scripting/modules.md)). An `import` of a name that matches no module fails the load of the file, like any other error in a file. A helper needed by two scripts is therefore repeated in both files, which is one more reason to keep scripts small.

The source of a file is decoded as UTF-8. Non-ASCII characters in strings are safe; saving the file in another encoding is not.

## When files are loaded

Loading is lazy and per engine instance. Each platform component that needs scripts gets its own script engine, which loads all the files the first time it is used. Nothing is cached: the files can be loaded several times within one request, and module-level variables are never shared.

Two consequences follow. First, a saved change applies from the next engine instance, that is, from the first request or job started once the new configuration version is visible; a request already running keeps the files it loaded. Second, the cost of loading is paid in the request that triggers it, which is why the top-level code of a file has to be fast.

## What happens when a file loads

The diagram shows the path from a request to a handler's return value.

```mermaid
flowchart TD
  A[Request or job needs a script] --> B[Script engine created]
  B --> C[Every file under server/scripts loaded]
  C --> D[Top-level code runs, within about 1 s]
  D --> E[Default export called with context]
  E --> F[context.register stores the handlers by key]
  F --> G[Platform calls the handler by exact name]
  G --> H[Return value converted by member name]
```

For each file, in this order:

1. The top-level code runs. It has to finish within about one second. This code should only declare constants and functions; network calls and loops over large data belong in handlers.
2. The file's default export is called with a `context` argument. A file must therefore contain `export default function (context) { ... }`.
3. Inside the default export, `context.register(key, handlers)` registers the handlers under a key. A file may register several keys, and a key may be registered several times by several files.

```js
function fill(entity) { /* ... */ }

export default function (context) {
  context.register('runtime.scriptable.passDataProvider.memberLookup', {
    Fill: fill,
  });
}
```

Helper functions can be declared with any name, because the platform never calls them by that name. What counts is the property name inside the `handlers` object: it is matched case-sensitively against the method the platform calls (see [Handlers](https://docs.thewalletcrew.io/developers-guides/scripting/handlers.md)). The order in which the files are loaded is not defined, and no script should depend on it.

A file without a default export function is skipped. The platform logs the warning `file <path> doesn't export default function` once per file and configuration version; later occurrences are logged at debug level, which is not recorded in the default production configuration.

## Time limits

Two limits apply. The top-level code of a file has to finish within about one second when the file loads. A handler that runs for more than 5 000 ms before its first `await` throws a `TimeoutException` with the message `A script handler ran for more than 5000 ms without returning`; code after an `await` is not timed by this limit. The second limit is why a loop over a large collection, or heavy computation, is split or moved to a scheduled job rather than run in a handler.

## One key, one file

When the platform needs a single handler for a key, it takes the last one registered. Because the load order of files is not defined, two files registering the same key make the winner unpredictable: a change in one file can silently replace the behavior of the other. Almost every endpoint works this way, so each key is registered in exactly one file.

The exceptions are deliberate:

| Key                                | Behavior with several registrations                                                                      |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `runtime.wallet.passUpdater`       | Every registered handler runs; each is isolated, so an error in one is logged and the others still run   |
| `runtime.wallet.applePassResolver` | Only one registration is allowed; more than one is an error                                              |
| `extensions.*` (connector scripts) | The last registered handler is used; the slot editor of the connector lists the other files as conflicts |
| All other keys                     | The last registered handler is used                                                                      |

Keys that contain a script id (`runtime.scriptable.passDataProvider.{scriptId}`, `runtime.scriptable.customerPipelineElement.{scriptId}`, `runtime.scriptable.pushUpdates.{scriptId}`, `runtime.scriptable.benefitTemplateCodeGenerator.{templateId}`) are one key per script id: two files may coexist as long as their ids differ. The full list of keys is in [Runtime endpoints](https://docs.thewalletcrew.io/developers-guides/scripting/endpoints.md) and in [Connector scripts](https://docs.thewalletcrew.io/developers-guides/scripting/extensions.md).

## When a file has an error

A JavaScript error in a file, whether a syntax error, an exception in the top-level code or an exception in the default export, is reported with the message `Error while executing file <path> - <reason>`. The loader continues with the other files so that it can report every faulty file, then fails as a whole: no script of the tenant is available while any file is faulty. A script that has nothing to do with the faulty file therefore fails too, at the next request that needs scripts.

This is the reason why scripts of a production tenant are changed with care, and why the save-time validation below exists.

## Validation when saving

Saving the whole advanced configuration runs the script loader against the configuration being saved. It parses every file, runs the top-level code and calls every default export, and reports each error as a configuration error, in the same format as above. A faulty file is therefore normally caught at save, before any request reaches it.

The validation has limits that matter:

* It does not check that a registered endpoint implements the methods the platform needs. A file that registers a pass data provider without a `Fill` is accepted, and fails only when the provider is reached.
* It does not check that a script id written in YAML (`scriptId` in a pass type or a flow, `scriptName` in a scheduler task) matches a registered script.
* It does not call any handler, so errors inside handlers and wrong return shapes are only found when the script really runs.
* Saving a single script file from the script editor of a connector extension does not run it.

Handlers are therefore exercised by running the real flow once, in a non-production tenant first, as described in [Best practices](https://docs.thewalletcrew.io/developers-guides/scripting/best-practices.md).

## Editor typings

The advanced configuration editor offers completion and documentation generated from the running platform: each endpoint with its handler signatures and parameter types, the globals, and the modules with their exports. Obsolete names appear with a deprecation mark. A signature shown in the editor is the reference when it differs from an older document. The editor reads the typings from `GET /api/{tenantId}/admin/configuration/script-typings`.

## FAQ

<details>

<summary><strong>Do scripts survive between requests, so that a variable could keep a counter or a cache?</strong></summary>

No. Each script engine loads the files again, so module-level variables start from scratch every time. Data that must be reused between requests goes through the `Cache` option of `fetch`, which is stored per tenant.

</details>

<details>

<summary><strong>A file was saved but the old behavior is still seen. Why?</strong></summary>

A request that started before the new configuration version became visible keeps the files it loaded. The next request loads the new version. "Refresh data" on the pass data page runs the providers again with the current files.

</details>

<details>

<summary><strong>Can a file register several endpoints?</strong></summary>

Yes. A file can call `context.register` several times, for different keys. It is often cleaner to keep one endpoint per file, named after the script id, so that the key, the id and the file name tell the same story.

</details>

<details>

<summary><strong>Is a different default export shape accepted, such as an arrow function or an async function?</strong></summary>

The default export has to be a function that takes the `context`. A function declaration is the form used throughout this documentation. Registration is synchronous: the function should not await anything before calling `context.register`. The loader calls the default export without waiting for the promise that an `async` function returns, so a registration placed after an `await` is not guaranteed to be in place when the first call arrives, and some forms, such as `await null`, make the file fail to load.

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.thewalletcrew.io/developers-guides/scripting/how-scripts-run.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
