vorkers

A CLI tool and library to build, deploy, and run vorker.js functions on your server.

Installation

As a CLI tool (global)

npm install -g vorkers

As a library (local)

npm install vorkers

Usage

CLI Usage

Setup

First, create a vorkers/index.ts file in your project:

// vorkers/index.ts
export function myFunction(data: any) {
  // Your function logic here
  return data;
}

Deploy Command

Build and deploy your vorker.js file:

vorkers deploy

This command will:

1. Look for vorkers/index.ts in your current directory
2. Build it into a minified dist/vorker.js bundle
3. Upload the built file to your configured server endpoint

Library Usage

Import and use vorkers functions in your Node.js project:

import { run, buildAndDeploy } from "vorkers";

// Run a vorker function on the server
const result = await run("omitKey", [{ name: "rafeeq", age: 28 }, ["name"]]);

console.log(result); // { age: 28 }

// Or build and deploy programmatically
await buildAndDeploy();

API Reference

run(functionName, data)

Execute a vorker function on the server.

Parameters:

• functionName (string): Name of the function to execute
• data (array): Array of arguments to pass to the function

Returns: Promise with the function result

Example:

import { run } from "vorkers";

// Call omitKey function
const result = await run("omitKey", [
  { name: "john", age: 30, city: "NYC" },
  ["age"],
]);

console.log(result); // { name: 'john', city: 'NYC' }

buildAndDeploy()

Build and deploy the vorker.js file to the server.

Returns: Promise that resolves when build and deploy are complete

Example:

import { buildAndDeploy } from "vorkers";

await buildAndDeploy();

Configuration

Environment Variables

Set the VORKERS_URL environment variable to configure the base URL for your vorkers server.

Option 1: Using .env file (Recommended)

Create a .env file in your project root:

VORKERS_URL=http://localhost:3000

The package will automatically load this file.

Option 2: Using shell environment variables

export VORKERS_URL=http://localhost:3000
# or
export VORKERS_URL=https://your-server.com

Endpoints

The package will automatically use this base URL for:

• Deploy endpoint: ${VORKERS_URL}/vorkers/deploy
• Run endpoint: ${VORKERS_URL}/vorkers/run

Example:

# Set the environment variable
export VORKERS_URL=https://api.example.com

# Then use the CLI or library
vorkers deploy

# Or in code
import { run } from 'vorkers';
const result = await run('omitKey', [{ name: 'test' }, ['name']]);

Project Structure

When using vorkers, your project should have this structure:

your-project/
├── vorkers/
│   └── index.ts          # Your vorker functions
├── dist/
│   └── vorker.js         # Generated bundle (created by build)
├── package.json
└── node_modules/

Example vorkers/index.ts

// vorkers/index.ts
import _ from "lodash";

export function omitKey(obj: Record<string, any>, keys: string[]) {
  return _.omit(obj, keys);
}

export function addNumbers(a: number, b: number) {
  return a + b;
}

// Export any functions you want to run on the server

Development

Install Dependencies

npm install
# or
bun install

Build TypeScript

npm run build
# or
npx tsc

Test Locally

Link the package locally to test the CLI:

npm link
# or with sudo if needed
sudo npm link

Then you can run:

vorkers deploy

Unlink

To remove the local link:

npm unlink -g vorkers-cli
# or
sudo npm unlink -g vorkers-cli

Publishing to npm

1. Update version in package.json
2. Build the project: npm run prepublishOnly
3. Login to npm: npm login
4. Publish: npm publish

Project Structure

.
├── bin/
│   └── vorkers.js       # CLI entry point
├── vorkers/
│   └── index.ts         # Vorker source code
├── example/
│   └── demo.ts          # Example functions
├── dist/
│   └── vorker.js        # Built output
├── index.ts             # Main build and deploy logic
└── build.js             # Build script

Requirements

• Node.js >= 18.0.0
• A server with /vorkers/deploy endpoint that accepts file uploads

License

MIT