{"id":13483853,"url":"https://github.com/architect/sandbox","last_synced_at":"2025-04-04T09:09:01.943Z","repository":{"id":35030743,"uuid":"189145916","full_name":"architect/sandbox","owner":"architect","description":"Architect dev server: run full Architect projects locally \u0026 offline in a sandbox","archived":false,"fork":false,"pushed_at":"2025-01-27T17:58:54.000Z","size":2691,"stargazers_count":37,"open_issues_count":6,"forks_count":33,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-03-28T08:08:10.035Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/architect.png","metadata":{"files":{"readme":"readme.md","changelog":"changelog.md","contributing":".github/contributing.md","funding":null,"license":"LICENSE","code_of_conduct":".github/code_of_conduct.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-05-29T03:43:19.000Z","updated_at":"2024-09-29T23:53:30.000Z","dependencies_parsed_at":"2023-01-15T12:23:22.263Z","dependency_job_id":"6c3900d6-dd4d-4813-a43a-73fcf71dbcf5","html_url":"https://github.com/architect/sandbox","commit_stats":{"total_commits":1254,"total_committers":27,"mean_commits":46.44444444444444,"dds":0.3110047846889952,"last_synced_commit":"589d6b78697707833ef092a7dcdf0c1a996903ff"},"previous_names":[],"tags_count":317,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/architect%2Fsandbox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/architect%2Fsandbox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/architect%2Fsandbox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/architect%2Fsandbox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/architect","download_url":"https://codeload.github.com/architect/sandbox/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247149501,"owners_count":20891954,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T17:01:16.021Z","updated_at":"2025-04-04T09:09:01.903Z","avatar_url":"https://github.com/architect.png","language":"JavaScript","readme":"[\u003cimg src=\"https://assets.arc.codes/architect-logo-500b@2x.png\" width=500\u003e](https://www.npmjs.com/package/@architect/sandbox)\n\n## [`@architect/sandbox`](https://www.npmjs.com/package/@architect/sandbox)\n\n\u003e Architect local development environment: run full Architect projects locally \u0026 offline in an in-memory sandbox\n\n[![GitHub CI status](https://github.com/architect/sandbox/workflows/Node%20CI/badge.svg)](https://github.com/architect/sandbox/actions?query=workflow%3A%22Node+CI%22)\n\n## Install\n\n```\nnpm i @architect/sandbox\n```\n\n---\n\n## CLI\n\n### Start the sandbox\n\n```\nnpx sandbox\n```\n\nOr if running Sandbox from within `@architect/architect`:\n\n```\nnpx arc sandbox\n```\n\n\n### CLI options\n\n- `-p`, `--port` - Manually specify HTTP port\n  - Defaults to `3333`\n- `-h`, `--host` - Specify the host interface for Sandbox to listen on\n  - Defaults to `0.0.0.0` (all available interfaces on your machine)\n  - To accept local connections only, specify `localhost`\n- `-v`, `--verbose` - Enable verbose logging\n- `-d`, `--debug` - Enable debug logging\n- `-q`, `--quiet` - Disable (most) logging\n- `--disable-delete-vendor` - Disable deleting Lambda vendor dirs upon startup\n- `--disable-symlinks` - Disable symlinking `src/shared` into all functions and use file copying instead\n\n\n### Environment variables\n\n- `ARC_API_TYPE` - Set the API Gateway API type\n  - Can be one of `http` (aliased to `httpv2`), `httpv1`, `rest`\n  - Defaults to `http`\n- `ARC_ENV` - `testing|staging|production`\n  - Defaults to `testing`\n- `ARC_HOST` - Specify the host interface for Sandbox to listen on\n  - Defaults to `0.0.0.0` (all available interfaces on your machine)\n  - To accept local connections only, specify `localhost`\n- `ARC_LOCAL`- If present and used in conjunction with `ARC_ENV=staging|production`, emulates live `staging` or `production` environment\n  - Uses your [local preferences `@env`](../configuration/local-preferences#%40env) environment variables for the appropriate stage\n  - Connects Sandbox to live AWS events and DynamoDB infrastructure\n  - Requires valid AWS credentials with the same profile name as defined in your [project manifest](../project-manifest/aws#profile)\n- Specify ports:\n  - `ARC_PORT` - Manually specify HTTP port\n    - Defaults to `3333`\n  - `ARC_EVENTS_PORT`- Manually specify event bus port\n    - Defaults to `4444`\n  - `ARC_TABLES_PORT`- Manually specify local DynamoDB port\n    - Defaults to `5555`\n  - `ARC_INTERNAL_PORT`- Manually specify internal Sandbox + AWS services port\n    - Defaults to `2222`\n- `ARC_DB_EXTERNAL` - (Boolean) Use an external DynamoDB tool (such as [AWS NoSQL Workbench](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/workbench.html))\n- `ARC_QUIET` - If present, disable (most) logging\n\n---\n\n## API\n\nSandbox is designed to be integrated into your application's test suite. In most cases you'll only need to make use of `sandbox.start()` and `sandbox.end()`. However, individual Sandbox services can also be individually started and stopped. ([See below](#individual-sandbox-services).)\n\nMethods may be passed an options object containing the following parameters:\n- `apigateway` - **String** - Specify the API Gateway API type\n  - Defaults to `http`\n  - Can be one of `http` (aliased to `httpv2`), `httpv1`, `rest`\n- `cwd` - **String** - Specify a working directory (handy for aiming Sandbox at test mocks)\n- `deleteVendor` - **Boolean** - Delete Lambda vendor dirs upon startup\n  - Defaults to `true`\n- `env` - **Object** - Environment variables for Lambda invocations in automated testing\n  - String values overwrite env vars of the same name set via `.env` or `prefs.arc` files\n  - `undefined` values delete any env vars of the same name set via `.env` or `prefs.arc` files\n- `port` - **String or Number** - Specify HTTP port\n  - Defaults to `3333`\n- `quiet` - **Boolean** - Disables (most) logging\n- `runStartupCommands` - **Boolean** - Disable `@sandbox-start` commands\n  - Defaults to `true`\n- `runtimeCheck` - **String** - Check for runtime version mismatches\n  - If set to `warn` Sandbox will warn of mismatches in stdout\n  - If set to `error` (suggested for test environments) Sandbox will fail to start up\n  - Does not run by default\n- `symlink` - **Boolean** - Use symlinking to Architect shared code from within each Lambda's dependencies (e.g. `src/http/get-index/node_modules/@architect/shared` → `src/shared`)\n  - Defaults to `true`\n  - `false` copies shared code into each Lambda, which can result much slower startup and dependency rehydration speeds\n- `watcher` - **Boolean** - Disable the Sandbox file watcher (and related Sandbox file watcher plugin API)\n  - Defaults to `true`\n\n---\n\n### Sandbox\n\n\u003e Start and shut down the Sandbox; unless you have specific per-service needs, we generally advise most folks use this interface for testing\n\n\n### `sandbox.start(options[, callback]) → [Promise]`\n\nStarts the Sandbox; first checks that ports are available to consume, prints a banner, loads Architect and userland environment variables, hydrates application dependencies, and starts various Sandbox services (including `@events`, `@queues`, `@tables`, `@indexes`, `@http`, `@static` and `@ws`).\n\nInvokes `callback` once everything is ready, or returns a `promise` if `callback` is falsy.\n\n\n### `sandbox.end([callback]) → [Promise]`\n\nShuts down anything started by `sandbox.start()`. Invokes `callback` once shut down, or returns a `promise` if `callback` is falsy.\n\n---\n\n## Example\n\n### Tape\n\n```javascript\nlet sandbox = require('@architect/sandbox')\nlet test = require('tape')\n\ntest('Start the Sandbox', async t =\u003e {\n  t.plan(1)\n  let result = await sandbox.start()\n  t.equal(result, 'Sandbox successfully started')\n})\n\ntest('Tests go here', t =\u003e {\n  // Make use of various Sandbox resources in your tests...\n})\n\ntest('Shut down the Sandbox', async t =\u003e {\n  t.plan(1)\n  let result = await sandbox.end()\n  t.equal(result, 'Sandbox successfully shut down')\n})\n```\n\n\n### Jest\n\n```javascript\nlet sandbox = require('@architect/sandbox')\n\nbeforeAll(async () =\u003e {\n  let result = await sandbox.start()\n  expect(result).toBe('Sandbox successfully started')\n})\n\nafterAll(async () =\u003e {\n  let result = await sandbox.end()\n  expect(result).toBe('Sandbox successfully shut down')\n})\n\ntest('Tests go here', () =\u003e {\n  // Make use of various Sandbox resources in your tests...\n})\n```\n\n## Development\n\n### Requirements\n\nThe tests in this repository require that you have the `deno` runtime installed on your local machine. Install `deno` by visiting: https://deno.land/#installation\n\n### Running Tests\n\nTo work on sandbox, first make sure you have installed the dependencies:\n\n    npm install\n\nTo run all tests, including the linter:\n\n    npm test\n\nTo run just the linter:\n\n    npm run lint\n\nTo run just the unit tests (which are located under `test/unit`):\n\n    npm run test:unit\n\nTo get a code coverage report based on unit test execution:\n\n    npm run coverage\n\nTo run just the integration tests (which are located under `test/integration'):\n\n    npm run test:integration\n\nTo make tests run extra noisy-like, add the `NOISY_TESTS=true` env var\n\n\n[events]: https://arc.codes/reference/arc/events\n[http]: https://arc.codes/reference/arc/http\n[queues]: https://arc.codes/reference/arc/queues\n[tables]: https://arc.codes/reference/arc/tables\n[ws]: https://arc.codes/reference/arc/ws\n","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farchitect%2Fsandbox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farchitect%2Fsandbox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farchitect%2Fsandbox/lists"}