Skip to main content

Development Tools

Start here:

npx queue-run dev
👋 Dev server listening on:
   http://localhost:8000
   ws://localhost:8000
✔ Compiled 11 files and copied 5 files
✔ Created manifest
   Watching for changes (Crtl+R to reload) …

The server watches the current working directory and reloads whenever it detects a change.

Commands​

The following commands are used for development.

build​

This command builds the current project but does not deploy it.

npx queue-run build

It will attempt to transpile and load the code, so would detect syntax error and broken imports.

It will also output the project manifest, so you can audit it. For example:

 HTTP API
───────────────────────────────────────────
 /               →  api/index.tsx
 /bookmarks[id]  →  api/bookmarks/[id].ts
 /bookmarksfeed  →  api/bookmarks/feed.tsx
 /bookmarks      →  api/bookmarks/index.ts

 WebSocket
───────────────────────────────────────────
 /               →  socket/index.ts

 Queues
───────────────────────────────────────────
 screenshots     →  queues/screenshots.ts

 Schedules
───────────────────────────────────────────
 0 0 * * *       →  schedules/daily.ts

dev​

This command runs the development server.

npx queue-run dev

The dev server lists on port 8000 for HTTP and WebSocket.

You can change the ports with the --port argument or PORT environment variable. Other commands (queue, schedule) would need to know that port number.

You can press Ctrl+C to exit the server, Ctrl+R to force a reload, and Ctrl+L to clear the screen.

The development server will load environment variables from the file .env file. You can also set environment variables with the -e option.

dev queue​

You can use this command to test a queued job using the dev server.

npx queue-run dev queue <name> [payload]
npx queue-run dev queue <name> @filename
npx queue-run dev queue <name> -

You can provide the job payload as:

  • Command line argument following the queue name
  • From a file, using a command line argument like @my_job.json
  • From standard input, using the command line argument -
  • From the terminal, QueueRun will prompt you

For a FIFO queue, you also need to specify the group ID using the --group option.

dev schedule​

You can use this command to test a scheduled job using the dev server.

npx queue-run dev schedule <name>

init​

Use this to initialize a new project.

npx queue-run init

It will ask you a few questions and then create appropriate files. See Project Files.

Project Files​

Use npx queue-run init to generate these files for a new project.

package.json​

You don't need to have a package.json, but if you do:

  • Set private: true unless you intend to publish it to the NPM registry
  • Set type: "module" so you can use CommonJS and ESM modules
  • You can add queue-run as peer dependency, since it's needed to run the project and already available as part of the runtime
  • You can set engines.node to the specific Node runtime
  • The imports are a convenience for using absolute instead of relative paths
{
  "engines": {
    "node": "14.x"
  },
  "imports": {
    "#api/*": "./api/*",
    "#lib/*": "./lib/*",
    "#queues/*": "./queues/*",
    "#schedules/*": "./schedules/*",
    "#socket/*": "./socket/*"
  },
  "peerDependencies": {
    "queue-run": "^0.0.0"
  },
  "private": true,
  "scripts": {
    "build": "queue-run build",
    "dev": "queue-run dev",
    "deploy": "queue-run deploy",
    "lint": "eslint **/*.{ts,tsx}"
  },
  "type": "module",
}

tsconfig.json​

QueueRun does not use tsconfig.json: it only uses pacakge.json.

If you're using an IDE like Visual Studio Code, it uses tsconfig.json to understand the structure of your TypeScript project.

npx queue-run init will generate this file for you, which you can change to add more strict checks. For example:

{
  "compilerOptions": {
    "esModuleInterop": true,
    "jsx": "react-jsx",
    "jsxImportSource": "queue-run",
    "paths": {
      "#api/*": ["./api/*"],
      "#lib/*": ["./lib/*"],
      "#queues/*": ["./queues/*"],
      "#schedules/*": ["./schedules/*"],
      "#socket/*": ["./socket/*"]
    },
    "strict": true,
  },
  "include": ["queue-run.env.d.ts", "**/*.ts", "**/*.tsx"]
}

.env​

Use this file to store environment variables for your backend when running in development.

The format for this file is name=value pairs, but it does support comments, and multi-line values:

# This is a comment
SECRET_KEY=YOURSECRETKEYGOESHERE # comment
SECRET_HASH="something-with-a-#-hash"
PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
...
Kh9NV...
...
-----END DSA PRIVATE KEY-----"

You cannot change the following environment variables: NODE_ENV, QUEUE_RUN_URL, QUEUE_RUN_WS, and QUEUE_RUN_ENV (see Environment Variables)

To manage environment variables in production, use the env command.

index.ts​

This file is shared by all backend resources (HTTP, queues, etc), use this for:

Testing WebSocket​

You can use CLI tool like websocat:

websocat ws://localhost:8000