From e2992509885362a150f88d4408085b0be59303a5 Mon Sep 17 00:00:00 2001
From: filmaj <maj.fil@gmail.com>
Date: Tue, 1 Jul 2025 21:00:23 -0400
Subject: [PATCH] docs: documenting missing sandbox preferences (`external-db`,
 `seed-data`) and clarifying around use of .mjs and .cjs files for seed data
 introduced via https://github.com/architect/sandbox/pull/739

---
 src/views/docs/en/reference/cli/sandbox.md     | 12 +++++++++++-
 .../configuration/local-preferences.md         | 18 ++++++++++++++++++
 2 files changed, 29 insertions(+), 1 deletion(-)

diff --git a/src/views/docs/en/reference/cli/sandbox.md b/src/views/docs/en/reference/cli/sandbox.md
index c6fec1a9..f91c9b6f 100644
--- a/src/views/docs/en/reference/cli/sandbox.md
+++ b/src/views/docs/en/reference/cli/sandbox.md
@@ -178,7 +178,7 @@ You can set a custom port by using an environment variable: `ARC_TABLES_PORT=555
 
 ### 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.)
+You can automatically seed data to Sandbox upon startup by adding a `sandbox-seed.[c|m]js` or `sandbox-seed.json` file to the root of your project. (You can also specify a custom path with [the `seed-data` preference](../configuration/local-preferences#seed-data---string).)
 
 Your seed data should be an object whose properties correspond to `@tables` names, and have arrays of rows to seed. For example:
 
@@ -205,6 +205,16 @@ module.exports = {
     }
   ]
 }
+// sandbox-seed.mjs
+export default {
+  things: [
+    {
+      id: 'foo',
+      sort: 'bar',
+      arbitrary: 'data',
+    }
+  ]
+}
 ```
 
 The above example would add the two rows above to the `things` database each time Sandbox is started.
diff --git a/src/views/docs/en/reference/configuration/local-preferences.md b/src/views/docs/en/reference/configuration/local-preferences.md
index 79e99482..0aa2df95 100644
--- a/src/views/docs/en/reference/configuration/local-preferences.md
+++ b/src/views/docs/en/reference/configuration/local-preferences.md
@@ -115,6 +115,15 @@ Advanced option: override the local environment to use `staging` or `production`
 env staging
 ```
 
+### `external-db` - Boolean
+
+Use an external database instead of Sandbox's built-in dynalite DynamoDB simulator. Useful if you'd rather work with a separate tool like [AWS NoSQL Workbench](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/workbench.html).
+
+```arc
+@sandbox
+external-db true
+```
+
 ### `useAWS` - Boolean
 
 Advanced option that instruct [Sandbox][sandbox] to use live AWS infrastructure where deployed, specifically: [`@tables`][tables] / [`@tables-indexes`][indexes] (DynamoDB), [`@events`][events] (EventBridge), and [`@queues`][queues] (SQS). Defaults to `false`. Notes:
@@ -135,6 +144,15 @@ Disables [hydration][hydrate]. Defaults to `false`.
 no-hydrate true
 ```
 
+### `seed-data` - String
+
+Specifies a custom file path to [Sandbox database seed data](../cli/sandbox#database-seed-data).
+
+```arc
+@sandbox
+seed-data scripts/sandbox-database-seed.mjs
+```
+
 ## `@sandbox-start`
 
 Hook up CLI commands into [Sandbox][sandbox] startup. Helpful for repetitive tasks like seeding a database or starting up additional services for local development. Each command should be a separate unindented line under the `@sandbox-start` pragma.