Promptable App

Appearance

Local Development Setup ​

This guide explains how to run the Promptable application and its Durable Object (DO) worker locally.

Prerequisites ​

  • Node.js (version 20 or as specified in CI workflows)
  • npm (comes with Node.js)
  • Cloudflare Wrangler CLI (can be installed via npm: npm install -g wrangler, or used via npx wrangler)

Running the Application ​

You'll need two separate terminal sessions.

1. Start the SvelteKit Application ​

From the project root directory:

a. Install dependencies (if you haven't already):bash npm install b. Build the application:bash npm run build Note: Currently, running npm run dev without a prior npm run build can lead to errors due to missing built packages. This is a known issue we plan to address.

c. Start the development server:bash npm run dev This typically starts the SvelteKit application on http://localhost:5173. This command often uses wrangler pages dev under the hood, which requires a local wrangler.toml or similar configuration in packages/app-worker/ to bind to the local Durable Object. See "Configuring Local DO Binding" below.

2. Start the Durable Object (DO) Worker ​

From the packages/do-runner directory in a separate terminal:

a. Navigate to the directory:bash cd packages/do-runner b. Install dependencies (if you haven't already):bash npm install c. Start the DO worker with Miniflare:bash npm run dev This command uses the packages/do-runner/wrangler.toml file to configure and run the ExecutionRunner Durable Object locally via Miniflare. You should see output indicating the worker is running.

Once both are running, you can access the application at http://localhost:5173. Running an automation in the app will trigger events in the local do-runner.

Configuring Local DO Binding for SvelteKit App ​

For the SvelteKit application (started from the root npm run dev) to communicate with your locally running Durable Object worker, it needs to be configured. This is typically done via a wrangler.toml file specific to the local development environment for the app worker, located in packages/app-worker/.

Recommended Setup:

  1. Create a file named packages/app-worker/wrangler.development.toml. This file should be added to your .gitignore to avoid committing local-specific configurations.

  2. Add the following content to packages/app-worker/wrangler.development.toml:

    toml
    # packages/app-worker/wrangler.development.toml
# This file is for local development bindings.
# Ensure your root `npm run dev` script (e.g., using `wrangler pages dev`)
# is configured to load this file (e.g., `wrangler pages dev --config=./packages/app-worker/wrangler.development.toml`)
# or that it loads bindings from a .dev.vars file if using Vite directly with emulated bindings.

name = "promptable-app-local-dev" # Optional: A name for your local Pages instance

[[durable_objects.bindings]]
name = "EXECUTION" # This is the binding name used in your SvelteKit code
class_name = "ExecutionRunner" # The DO class name
script_name = "execution-runner-worker" # Points to the 'name' in packages/do-runner/wrangler.toml
# For Miniflare, 'script_name' helps it find the DO implementation from the other worker
# when both are running locally.

  3. Commit an example file: Create a copy of this file named packages/app-worker/wrangler.development.example.toml and commit it to the repository. This provides a template for other developers. Replace any sensitive or user-specific values in the example file if necessary (though for local bindings, this is usually not the case). The content for packages/app-worker/wrangler.development.example.toml is provided in a separate step.

  4. Ensure your root npm run dev script (likely in the root package.json) is configured to use this wrangler.development.toml. If it uses wrangler pages dev ..., you might need to add a --config=packages/app-worker/wrangler.development.toml flag or ensure it picks up a wrangler.toml from packages/app-worker and that you create that packages/app-worker/wrangler.toml by copying the .development version. Alternatively, if your SvelteKit dev server (e.g., Vite) directly supports Cloudflare bindings (e.g., via @cloudflare/vite-plugin-cloudflare-functions or similar), you might configure these bindings in vite.config.js and use a .dev.vars file in packages/app-worker/ for the binding details. The principle remains: the local SvelteKit app needs to know about the local DO.

    Note: The exact mechanism for loading this local configuration by the SvelteKit npm run dev script depends on its implementation (e.g., direct vite vs. wrangler pages dev). Adjust the instructions if your setup uses a different convention (like a .dev.vars file in packages/app-worker/).

Environment Variables ​

If your application requires other environment variables for local development (e.g., API keys not related to Cloudflare bindings), consider creating a .env.example file in the root directory and/or relevant package directories (e.g., packages/app-worker/.env.example) to list required variables. Developers can then copy this to a .env file (which should be gitignored) and fill in their values.

Local Cloudflare Environment Variables (.dev.vars) ​

For services like app-worker and do-runner that might load local environment variables through Wrangler's .dev.vars convention (these are automatically loaded by wrangler dev or wrangler pages dev if present in the respective package directory):

  • Create Example Files: It is highly recommended to create example files for these as well:
    • packages/app-worker/.dev.vars.example
    • packages/do-runner/.dev.vars.example
  • Content: These files should list the required variable names, perhaps with placeholder or example values, e.g.:
    # packages/app-worker/.dev.vars.example
SOME_API_KEY="your_api_key_here"
ANOTHER_SETTING="default_value"
  • Usage: Developers should copy these .dev.vars.example files to .dev.vars in the corresponding directories and populate them with their actual local development values.
  • Gitignore: Ensure that the actual .dev.vars files are included in your project's .gitignore file to prevent committing local-specific or sensitive variables.