arc sandbox
Architect projects work locally and offline. Sandbox emulates most app resources defined in app.arc
:
@http
@static
@ws
@events
@queues
@tables
and@tables-indexes
Additionally,
@scheduled
and@tables-streams
Lambdas can be emulated via the @architect/plugin-lambda-invoker plugin
Usage
arc sandbox [--port|--host|--disable-symlinks|--no-hydrate|--verbose]
Flags
-p
,--port
- Manually specify HTTP port- Defaults to
3333
- Defaults to
-h
,--host
- Specify the host interface for Sandbox to listen on- Defaults to
0.0.0.0
(all available interfaces on your machine) - To accept local connections only, specify
localhost
- Defaults to
-v
,--verbose
- Enable verbose logging-d
,--debug
- Enable debug logging-q
,--quiet
- Disable (most) logging--disable-symlinks
- Disable symlinkingsrc/shared
into all functions and use file copying instead
CLI variables
The following variables can be set on the command line when running arc sandbox
. Other variables will be ignored by Sandbox.
ARC_API_TYPE
- Set the API Gateway API type- Can be one of
http
(aliased tohttpv2
),httpv1
,rest
- Defaults to
http
- Can be one of
ARC_ENV
-testing|staging|production
- Defaults to
testing
- Defaults to
ARC_HOST
- Specify the host interface for Sandbox to listen on- Defaults to
0.0.0.0
(all available interfaces on your machine) - To accept local connections only, specify
localhost
- Defaults to
ARC_LOCAL
- If present and used in conjunction withARC_ENV=staging|production
, emulates livestaging
orproduction
environment- Uses your local preferences
@env
environment variables for the appropriate stage - Connects Sandbox to live AWS events and DynamoDB infrastructure
- Requires valid AWS credentials with the same profile name as defined in your project manifest
- Uses your local preferences
- Specify ports:
ARC_PORT
- Manually specify HTTP port- Defaults to
3333
- Defaults to
ARC_EVENTS_PORT
- Manually specify event bus port- Defaults to
4444
- Defaults to
ARC_TABLES_PORT
- Manually specify local DynamoDB port- Defaults to
5555
- Defaults to
ARC_INTERNAL_PORT
- Manually specify internal Sandbox + AWS services port- Defaults to
2222
- Defaults to
ARC_DB_EXTERNAL
- (Boolean) Use an external DynamoDB tool (such as AWS NoSQL Workbench)ARC_QUIET
- If present, disable (most) logging
Example
Run Sandbox in quiet mode on a different port:
ARC_QUIET=1 PORT=8888 npx arc sandbox
Local preferences
Several Architect local preferences can be leveraged to change how Sandbox works while developing locally.
@sandbox
The following can be set as a part of the @sandbox
pragma.
livereload
- Enable live automatic reload for@http
get
andany
functions that deliver HTML. When a filesystem change is detected in the handler or in shared or views code, open browser sessions will automatically refresh.- Defaults to
false
- Defaults to
env
* - Override the local environment setting to usestaging
orproduction
so that Sandbox uses that stage’s environment variables as set in local preferences@env
or in the project’s.env
file.- Can be one of
testing
(default),staging
, orproduction
- Can be one of
useAws
* - Use live AWS infrastructure from Sandbox. Specifically,@tables
,@tables-indexes
,@events
, and@queues
.- Uses the
staging
environment by default, butenv
can be set toproduction
. - Defaults to
false
- Uses the
no-hydrate
- Disable function hydration on Sandbox start.- Defaults to
false
- Defaults to
seed-data
- Specify a custom file path for seed data to populate@tables
with on startup- Defaults to
./sandbox-seed.json
,./sandbox-seed.js
- Defaults to
external-db
- (Boolean) Use an external DynamoDB tool (such as AWS NoSQL Workbench)
@sandbox
livereload true
env production
useAws true
no-hydrate true
* These advanced options should be used with care since they will allow local development code to interact with live AWS resources.
@sandbox-startup
Additionally, Sandbox can run shell commands on startup by setting @sandbox-startup
in local preferences.
@sandbox-startup
node scripts/seed_db.js
echo 'hello'
@create
Upon starting, Sandbox can automatically scaffold resources (via arc init
) found in the application’s manifest that do not yet exist. Options are set with @create
in local preferences.
autocreate
- Set totrue
to enable automatic creation of boilerplate Lambda handlers and static assets if they do not exist.templates
- Specify templates for automatic resource scaffolding.<pragma name> path/to/template.ext
- Does not enable
autocreate
@create
autocreate true
templates
http path/to/template/http.js
events path/to/template/events.py
@env
Architect Sandbox will load variables for Sandbox’s current environment (testing
, staging
, or production
) from a local preferences file with @env
. If a project contains a .env
file, Architect will load those variables instead.
Variables from local preference files and .env
will not be merged. Further details, including the variable load-strategy are outlined below.
Environment variables
Sandbox automatically loads environment variables for availability at runtime (process.env.MY_VAR
in Node.js). Environment variables can be set in a few locations. It’s important to understand how each source is prioritized when developing locally.
Load strategy
Sandbox will prioritize…
- A project’s
.env
file (if it exists), - then project-level Architect preferences,
- and finally global Architect preferences.
Variables across these sources are not merged.
Using a local preferences file with @env
offers the most flexibility since variables can be specified per environment: testing
, staging
, and production
.
Example scenario
If .env
is found, Sandbox will not load any variables from any Arc preferences. Given the following case with 3 environment variable sources:
# ./.env
URL="https://arc.codes"
# ./prefs.arc
@env
testing
URL www.architect.fake
# ~/.preferences.arc
@env
testing
URL ftp://arc.ftp
ADMIN_PASS zero cool
The following is true in a Node.js function run with Sandbox:
process.env.URL === 'https://arc.codes' // true
process.env.ADMIN_PASS // undefined
Local database
Sandbox creates an in-memory instance of dynalite with @tables
and @tables-indexes
found in the app.arc
file. @tables-streams
is not currently supported by dynalite.
When Sandbox is terminated, any data written is cleared from memory.
You can set a custom port by using an environment variable: ARC_TABLES_PORT=5555
.
Database seed data
You can automatically seed data to Sandbox upon startup by adding a sandbox-seed.js
or sandbox-seed.json
file to the root of your project. (You can also specify a custom path with the seed-data
preference.)
Your seed data should be an object whose properties correspond to @tables
names, and have arrays of rows to seed. For example:
@tables
things
id *String
sort **String
// seed-data.js
module.exports = {
things: [
{
id: 'foo',
sort: 'bar',
arbitrary: 'data',
},
{
id: 'fiz',
sort: 'buz',
arbitrary: 'info',
}
]
}
The above example would add the two rows above to the things
database each time Sandbox is started.
Note: This feature is only enabled if the environment is
testing
, so as to prevent the accidental (over)writing of data to a live database.
Live database example
Connect Sandbox to the DynamoDB staging database on AWS:
ARC_ENV=staging ARC_LOCAL=1 npx arc sandbox