\n\n> ⚠️ **DEPRECATION NOTICE**: `@mockoon/serverless` is deprecated and will be removed in a future major version. We recommend using the **[Mockoon CLI Docker image](https://hub.docker.com/r/mockoon/cli)** (`mockoon/cli`) or `@mockoon/cli` in containerized serverless runtimes (AWS Lambda container images, Google Cloud Run, AWS Fargate, Azure Container Apps, etc.).\n>\n> 📖 See the [Mockoon CLI Docker documentation](https://github.com/mockoon/mockoon/tree/main/packages/cli#docker-image) for setup instructions.\n\nMockoon's Serverless package provides an easy way to run Mockoon's mock APIs in cloud functions and serverless environments: AWS Lambda, GCP Functions, Firebase Functions, etc.\n\nThe Serverless package supports the same features as the main [application](https://github.com/mockoon/mockoon/blob/main/packages/app) and [CLI](https://github.com/mockoon/mockoon/blob/main/packages/cli) (with some limitations, see below): [templating system](https://mockoon.com/docs/latest/templating/overview/), [proxy mode](https://mockoon.com/docs/latest/server-configuration/proxy-mode/), [route response rules](https://mockoon.com/docs/latest/route-responses/dynamic-rules/), etc.\n\n## Migration to Docker image (`mockoon/cli`)\n\nInstead of maintaining custom serverless wrapper functions, we recommend running Mockoon's official Docker image in containerized serverless services:\n\n```bash\ndocker run -d -p 3000:3000 mockoon/cli:latest --data https://raw.githubusercontent.com/mockoon/mock-samples/main/samples/generate-mock-data.json --port 3000\n```\n\nFor more details on running Mockoon with Docker, check out our [Docker documentation](https://github.com/mockoon/mockoon/tree/main/packages/cli#docker-image).\n\n## Using this package (Deprecated)\n\n### Installation\n\n```sh-session\n$ npm install @mockoon/serverless\n```\n\n### Mockoon's data file\n\nThe Serverless package needs a Mockoon `Environment` object loaded from a [data file](https://mockoon.com/docs/latest/mockoon-data-files/data-files-location/).\nYou are responsible for loading this data file (from a URL, S3, etc.) and providing the object to the class constructor (see below).\n\nIn the examples below, we will be loading the data file as if it was located next to your function's main file.\n\n### Request listener (Express application)\n\nThis package exposes a single `MockoonServerless` class. To create a new `RequestListener` (an Express application), use the following code:\n\n```javascript\nconst mockoon = require('@mockoon/serverless');\n\n// Load the Mockoon Environment object\nconst mockEnv = require('./datafile.json');\n\nconst app = new mockoon.MockoonServerless(mockEnv);\n\nexports.handler = app;\n```\n\nFor vendor-specific code, see the sections below.\n\n### AWS Lambda\n\nTo use Mockoon Serverless in an AWS Lambda, you can use the following code:\n\n```javascript\nconst mockoon = require('@mockoon/serverless');\n\n// Load the Mockoon Environment object\nconst mockEnv = require('./datafile.json');\n\nconst mockoonServerless = new mockoon.MockoonServerless(mockEnv);\n\nmodule.exports.handler = mockoonServerless.awsHandler();\n```\n\n`@mockoon/serverless` is using the [`serverless-http`](https://www.npmjs.com/package/serverless-http) package to wrap Mockoon's Express.js API.\n\n### Firebase/GCP Functions\n\nTo use Mockoon Serverless in a Firebase Function, you can use the following code:\n\n```javascript\nconst { onRequest } = require('firebase-functions/v2/https');\nconst mockoon = require('@mockoon/serverless');\n\n// Load the Mockoon Environment object\nconst mockEnv = require('./datafile.json');\n\nconst app = new mockoon.MockoonServerless(mockEnv).firebaseApp();\n\nexports.app = onRequest(app);\n```\n\nSince Firebase Functions uses GCP Functions underhood, a slightly different approach can be used with the [functions-framework-nodejs](https://github.com/GoogleCloudPlatform/functions-framework-nodejs):\n\n```javascript\nconst functions = require('@google-cloud/functions-framework');\nconst mockoon = require('@mockoon/serverless');\n\n// Load the Mockoon Environment object\nconst mockEnv = require('./datafile.json');\n\nconst app = new mockoon.MockoonServerless(mockEnv).firebaseApp();\n\nfunctions.http('app', app);\n```\n\n### Netlify Functions\n\nTo use Mockoon Serverless with Netlify's serverless functions, first create a new Netlify function with the following code:\n\n```javascript\nconst mockoon = require('@mockoon/serverless');\n\n// Load the Mockoon Environment object\nconst mockEnv = require('./datafile.json');\n\nconst mockoonServerless = new mockoon.MockoonServerless(mockEnv);\n\nexports.handler = mockoonServerless.netlifyHandler();\n```\n\nIf you're not sure how to create a Netlify function, please [read their official documentation](https://docs.netlify.com/functions/create/?fn-language=js).\n\nThen, you will need to setup a [redirect](https://docs.netlify.com/integrations/frameworks/express/) to direct requests to the mock API. A prefix like `api` is frequently used to distinguish between the requests targeting hosted websites, from requests targeting the API. Netlify will forward the full path to the running Mockoon serverless function which means that you need the [same prefix in your mock](https://mockoon.com/docs/latest/api-endpoints/routing/#api-prefix) configuration.\nTo add this redirection in your `netlify.toml` you have two possibilities:\n\n```toml\n[[redirects]]\n force = true\n from = \"/api/*\"\n status = 200\n to = \"/.netlify/functions/{NAME_OF_YOUR_FUNCTION}/api/:splat\"\n```\n\nor\n\n```toml\n[[redirects]]\n force = true\n from = \"/api/*\"\n status = 200\n to = \"/.netlify/functions/{NAME_OF_YOUR_FUNCTION}\"\n```\n\nAfter deploying to Netlify, any request starting with `/api/*` (e.g. `https://APP_NAME.netlify.app/api/endpoint`) would match the corresponding route (e.g. `/api/endpoint`) in your Mockoon config. You can also test locally using the Netlify CLI.\n\n## Options\n\nThe `MockoonServerless` class accepts an optional `options` object as a second parameter. The following options are available:\n\n| Option name | Type | Default value | Description |\n| --------------------- | ---------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `logTransaction` | `boolean` | `false` | [Enable full transaction logging](#transaction-logging) (see below). |\n| `disabledRoutes` | `string[]` | `[]` | Disable route(s) by UUID or keyword present in the route's path (do not include a leading slash) or keyword present in a folder name (see [below](#disabling-routes)). Use `['*']` to disable all routes. |\n| `fakerOptions.locale` | `string` | `[]` | Faker locale (e.g. 'en', 'en_GB', etc. For supported locales, see [below](#fakerjs-options).) |\n| `fakerOptions.seed` | `number` | `[]` | Number for the Faker.js seed (e.g. 1234) |\n| `envVarsPrefix` | `string` | `MOCKOON_` | [Environment variables prefix](https://mockoon.com/docs/latest/variables/environment-variables/). Pass an empty string to disable it. |\n| `enableAdminApi` | `boolean` | `true` | Enable (default) or disable the [Admin API](https://mockoon.com/docs/latest/admin-api/overview/). |\n| `adminApiAuthToken` | `string` | `undefined` | Admin API bearer token. Required when `enableAdminApi` is `true` if `MOCKOON_ADMIN_API_TOKEN` is not set. |\n| `adminApiCorsOrigins` | `string[]` | `undefined` | Allowed CORS origins for the admin API (e.g. `['https://app.example.com']`). When omitted, no CORS headers are emitted on admin API responses. Include `'*'` to explicitly opt into wildcard CORS. |\n| `disableTls` | `boolean` | `false` | Disable TLS. TLS configuration is part of the environment configuration (more info: https://mockoon.com/docs/latest/server-configuration/serving-over-tls/). |\n| `maxTransactionLogs` | `number` | `100` | Maximum number of transaction logs to keep in memory for retrieval via the admin API (default: 100). |\n| `enableRandomLatency` | `boolean` | `false` | Randomize global and responses latencies between 0 and the specified value (default: false). |\n\nExample:\n\n```javascript\nconst mockoonServerless = new mockoon.MockoonServerless(mockEnv, {\n logTransaction: true,\n // disable all routes containing 'users' in their path, and the route with UUID '0999df54-7d57-407e-9325-c18d97fea729'\n disabledRoutes: ['users', '0999df54-7d57-407e-9325-c18d97fea729'],\n // or disable all routes\n // disabledRoutes: ['*'],\n fakerOptions: {\n locale: 'en_GB',\n seed: 1234\n },\n envVarsPrefix: 'CUSTOM_PREFIX_',\n enableAdminApi: false,\n adminApiAuthToken: 'my-token',\n disableTls: true,\n enableRandomLatency: false\n});\n```\n\n### Admin API\n\nEach running mock API has an admin API enabled by default and available at `/mockoon-admin/`. This API allows you to interact with the running mock API, retrieve logs, and more. You can disable it by setting `enableAdminApi: false` in the constructor options.\n\nWhen the admin API is enabled, bearer authentication is always enabled.\n\nYou can provide the admin API token with `adminApiAuthToken` (or `MOCKOON_ADMIN_API_TOKEN`). When `enableAdminApi` is `true`, a token must be provided.\n\nSend the token with the `Authorization: Bearer ` header.\n\nBy default, the admin API does not emit CORS headers, which prevents browser-based cross-origin requests. To allow specific origins, set `adminApiCorsOrigins`:\n\n```javascript\nconst mockoonServerless = new mockoon.MockoonServerless(mockEnv, {\n adminApiCorsOrigins: ['https://app.example.com']\n});\n```\n\nOnly requests whose `Origin` header matches one of the allowed values receive CORS headers. Include `'*'` in the array to explicitly opt into wildcard CORS (not recommended for exposed instances).\n\nTransaction logs returned by the admin API (`GET /mockoon-admin/logs` and the SSE event stream) have known-sensitive headers redacted (`authorization`, `proxy-authorization`, `cookie`, `set-cookie`, `x-api-key`, `api-key`, `x-auth-token`). For `authorization` / `proxy-authorization`, the auth scheme is preserved (e.g. `Bearer [REDACTED]`). Request and response bodies are not modified.\n\n> 💡 To learn more about the admin API, check the [documentation](https://mockoon.com/docs/latest/admin-api/overview/).\n\n### Faker.js options\n\n- **Locale**: If not provided, Faker.js will use the default locale: `en`. For a list of currently supported locales, you can check the [supported locales list](https://github.com/mockoon/mockoon/blob/main/packages/commons/src/models/faker.model.ts#L1) in Mockoon's commons library. You can also check [Faker.js locales list](https://fakerjs.dev/guide/localization.html#available-locales) for more information (⚠️ Some locales may not yet be implemented in Mockoon).\n- **Seed**: If not provided, Faker.js will not use a seed. By providing a seed value, you can generate repeatable sequences of fake data. Using seeding will not always generate the same value but rather a predictable sequence.\n\n## Logging\n\nMockoon's Serverless package logs all server events (start, stop, proxy creation, transactions, etc.) to the console. You can also enable full transaction logging to log all requests and responses (see below).\n\n### Transaction logging\n\nWhen using the `logTransaction` option, logs will contain the full transaction (request and response) with the same information you can see in the desktop application \"Logs\" tab.\n\nExample:\n\n```json\n{\n \"app\": \"mockoon-server\",\n \"level\": \"info\",\n \"message\": \"Transaction recorded\",\n \"timestamp\": \"YYYY-MM-DDTHH:mm:ss.sssZ\",\n \"environmentName\": \"Demo API\",\n \"environmentUUID\": \"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\",\n \"requestMethod\": \"GET\",\n \"requestPath\": \"/test\",\n \"requestProxied\": false,\n \"responseStatus\": 200,\n \"transaction\": {\n \"proxied\": false,\n \"request\": {\n \"body\": \"{}\",\n \"headers\": [{ \"key\": \"accept\", \"value\": \"*/*\" }],\n \"method\": \"GET\",\n \"params\": [],\n \"query\": \"\",\n \"queryParams\": {},\n \"route\": \"/test\",\n \"urlPath\": \"/test\"\n },\n \"response\": {\n \"body\": \"{}\",\n \"headers\": [\n { \"key\": \"content-type\", \"value\": \"application/json; charset=utf-8\" }\n ],\n \"statusCode\": 200,\n \"statusMessage\": \"OK\"\n },\n \"routeResponseUUID\": \"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\",\n \"routeUUID\": \"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx\"\n }\n}\n```\n\nTo enable full transaction logging, set `logTransaction` to `true` in the constructor options:\n\n```javascript\nconst mockoonServerless = new mockoon.MockoonServerless(mockEnv, {\n logTransaction: true\n});\n```\n\nThe `transaction` model can be found [here](https://github.com/mockoon/mockoon/blob/main/packages/commons/src/models/server.model.ts#L27-L47).\n\n## Disabling routes\n\nYou can disable routes at runtime by providing their UUIDs or a keyword present in the route's path (do not include a leading slash). You can also disable all the routes present in a folder (including subfolders) by adding a keyword present in a folder name.\n\nThis is the counterpart of the \"Toggle route\" feature in the desktop application (right-click on a route -> \"Toggle route\").\n\nFor example, to disable all routes in a folder named `folder1`, and all routes having \"users\" in their paths, you can provide the following array `['folder1', 'users']`.\n\nTo disable all routes, you can pass an array containing a single string with a wildcard: `['*']`.\n\n## Serverless package limitations\n\nDue to the stateless nature of cloud functions, some of Mockoon's features will not work:\n\n- the [data buckets](https://mockoon.com/docs/latest/data-buckets/overview/) will not be persisting and be regenerated during each call.\n- the [rules](https://mockoon.com/docs/latest/route-responses/dynamic-rules/#1-target) based on the request number will not work as this counter will be reset during each call.\n\n## Mockoon's documentation\n\nYou will find Mockoon's [documentation](https://mockoon.com/docs/latest/about/) on the official website.\n\n## Support us!\n\nMockoon is proudly **independent** and **open-source**, maintained without external funding. We rely on both **sponsorships** and **Mockoon Cloud subscriptions** to keep improving the project and building new features. A **big thank you** to the companies below for supporting our work and helping us grow (and all the [sponsors](https://github.com/mockoon/mockoon/blob/main/backers.md) who helped this project over time!):\n\n### Platinum\n\n
\n\nIf you'd like to **support Mockoon** as well, you can **become a sponsor** or **subscribe to Mockoon Cloud**, every contribution helps keep the project alive and evolving. Thank you!\n\n
\n\n
\n\n## Subscribe to Mockoon Cloud\n\nWith advanced features for solo developers and teams, Mockoon Cloud supercharges your API development:\n\n- ☁️ [cloud deployments](https://mockoon.com/cloud/docs/api-mock-cloud-deployments/)\n- 🔄️ [data synchronization and real-time collaboration](https://mockoon.com/cloud/docs/data-synchronization-team-collaboration/)\n- 🤖 [AI powered API mocking](https://mockoon.com/ai-powered-api-mocking/)\n- 📃 Access to dozens of [ready-to-use JSON templates](https://mockoon.com/templates/).\n- 💬 Priority support and training.\n\nUpgrade today and take your API development to the next level.\n\n
\n\n
\n\n## Support/feedback\n\nYou can discuss all things related to Mockoon's CLI, and ask for help, on the [official community](https://github.com/mockoon/mockoon/discussions). It's also a good place to discuss bugs and feature requests before opening an issue on this repository.\n\n## Contributing\n\nIf you are interested in contributing to Mockoon, please take a look at the [contributing guidelines](https://github.com/mockoon/mockoon/blob/main/CONTRIBUTING.md).\n\nPlease also take a look at our [Code of Conduct](https://github.com/mockoon/.github/blob/main/CODE_OF_CONDUCT.md).\n\n## Roadmap\n\nIf you want to know what will be coming in the next release you can check the global [Roadmap](https://mockoon.com/public-roadmap/) or [subscribe to our newsletter](https://mockoon.com/newsletter/).\n","readmeFilename":"README.md"}
![](\"https://mockoon.com/images/logo-square-serverless.png\"){kind=logo}
\n \n ![](\"https://img.shields.io/badge/Download%20app-Go-green.svg?style=flat-square&colorB=1997c6\"/){kind=icon}
\n ![](\"https://img.shields.io/badge/Website-Go-green.svg?style=flat-square&colorB=1997c6\"/){kind=icon}
\n ![](\"https://img.shields.io/badge/Newsletter-Subscribe-green.svg?style=flat-square\"/){kind=icon}
\n ![](\"https://img.shields.io/npm/v/@mockoon/serverless.svg?style=flat-square&colorB=cb3837\"/)
\n ![\"emqx](\"https://mockoon.com/images/sponsors/emqx.png\")
\n \n![\"sponsor](\"https://mockoon.com/images/sponsor-btn.png?\")
\n![\"cloud](\"https://mockoon.com/images/cloud-btn.png?\")
\n![\"GitHub](\"https://mockoon.com/images/sponsors/light/github.png\")
\n ![\"Localazy](\"https://mockoon.com/images/sponsors/light/localazy.png\")
\n ![\"SerpApi](\"https://mockoon.com/images/sponsors/light/serpapi.png\")
\n ![\"CodeRabbit](\"https://mockoon.com/images/sponsors/light/coderabbit.png\")
\n ![\"TestMu](\"https://mockoon.com/images/sponsors/light/testmuai.png\")
\n