Expert guidance for working with Immich Workers - a monorepo of Cloudflare Workers providing backend/API services. Handles development, testing, deployment, and infrastructure management.
You are an expert at working with the Immich Workers repository - a monorepo for Cloudflare Workers that provide backend/API services deployed independently from frontend applications.
This is a pnpm workspace monorepo containing multiple Cloudflare Workers with shared tooling, testing infrastructure, and Terraform-based deployment.
```
apps/
├── hello/ # Example hello world worker
└── .../ # Other worker applications
deployment/
├── modules/ # Terraform modules
│ └── cloudflare/
│ └── workers/
│ └── <worker-name>/ # Worker-specific Terraform config
└── state.hcl # Terragrunt state configuration
src/
└── lib/ # Shared libraries and utilities (planned)
```
When working at the repository root, use these commands:
```bash
pnpm install # Install all dependencies
pnpm run lint # Lint all workers (eslint . --max-warnings 0)
pnpm run lint:fix # Auto-fix linting issues
pnpm run format # Check formatting with Prettier
pnpm run format:fix # Auto-fix formatting issues
pnpm run test # Run all tests in all workers
pnpm run check # Type-check all workers (tsc --noEmit && pnpm -r typecheck)
pnpm run build # Build all workers (pnpm -r build)
```
When working on a specific worker in `apps/<worker-name>/`:
```bash
pnpm run dev # Start development server with Wrangler
pnpm run build # Build for production (dry-run deploy to dist/)
pnpm run tail # Tail production logs
pnpm run test # Run tests with Vitest
pnpm run check # Type-check worker (tsc --noEmit)
```
Each worker in `apps/<worker-name>/` must contain:
Workers use Vitest with Cloudflare's test utilities. Access the worker via `SELF`:
```typescript
import { SELF } from 'cloudflare:test';
import { describe, expect, it } from 'vitest';
describe('Worker', () => {
it('should handle request', async () => {
const response = await SELF.fetch('https://example.com/');
expect(response.status).toBe(200);
});
});
```
The base Vitest configuration at `vitest.base.config.ts` uses `@cloudflare/vitest-pool-workers` for proper Worker environment emulation.
Follow these steps to create a new worker:
1. **Create directory structure**:
```bash
mkdir -p apps/<worker-name>/src
```
2. **Copy template from hello worker**:
- Use `apps/hello/` as reference template
- Copy: `package.json`, `wrangler.toml`, `tsconfig.json`, `vitest.config.ts`
3. **Update `wrangler.toml`**:
- Set `name = "<worker-name>-immich-app"`
- Configure KV namespaces, Durable Objects, or other bindings as needed
4. **Implement worker logic** in `src/index.ts`:
- Export default object with `fetch` handler
- Follow common patterns (see below)
5. **Add tests** in `src/index.test.ts`:
- Use Vitest with `SELF` import
- Test main request paths and error cases
6. **Create Terraform module**:
- Copy `deployment/modules/cloudflare/workers/hello/` as template
- Update `app_name` in `terragrunt.hcl` to match worker name
7. **Test locally**:
```bash
cd apps/<worker-name>
pnpm run dev
pnpm run test
```
All workers should export a default object with a fetch handler:
```typescript
export default {
async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
const url = new URL(request.url);
switch (url.pathname) {
case '/':
return new Response(JSON.stringify({ message: 'Hello' }), {
headers: { 'Content-Type': 'application/json' },
});
default:
return new Response('Not Found', { status: 404 });
}
},
};
```
All API responses include CORS headers for cross-origin access:
```typescript
headers: {
'Content-Type': 'application/json',
'Access-Control-Allow-Origin': '*',
}
```
Use consistent error response formatting:
```typescript
return new Response(
JSON.stringify({
error: 'Not Found',
path: url.pathname,
}),
{
status: 404,
headers: {
'Content-Type': 'application/json',
'Access-Control-Allow-Origin': '*',
},
},
);
```
Create `.dev.vars` in the worker directory (gitignored) for local secrets:
```
SECRET_KEY=local_secret
API_ENDPOINT=https://api.example.com
```
Set production secrets using Wrangler:
```bash
wrangler secret put SECRET_KEY
```
Or configure via Terraform in the worker module's infrastructure code.
Deploy directly from worker directory (deploy scripts not yet configured):
```bash
cd apps/<worker-name>
wrangler deploy # Deploy to production
wrangler deploy --env staging # Deploy to staging environment
```
Each worker has a Terraform module in `deployment/modules/cloudflare/workers/<worker-name>/`:
**Required environment variables**:
```bash
export TF_VAR_tf_state_postgres_conn_str="postgresql://user:pass@host/dbname"
export TF_VAR_env="dev" # Environment (dev/staging/prod)
export TF_VAR_stage="" # Stage suffix (optional)
export TF_VAR_app_name="hello" # Worker app name
export TF_VAR_cloudflare_account_id="your-account-id"
```
**Terraform workflow**:
```bash
cd deployment/modules/cloudflare/workers/<worker-name>
terragrunt init
terragrunt plan
terragrunt apply
```
**Key Terraform patterns**:
1. **Always run tests** before committing changes: `pnpm run test`
2. **Run linting and formatting** to maintain code quality: `pnpm run lint:fix && pnpm run format:fix`
3. **Type-check all changes**: `pnpm run check`
4. **Use the hello worker** as reference template for new workers
5. **Follow CORS and error patterns** for consistency across all workers
6. **Test locally** with `pnpm run dev` before deploying
7. **Document environment variables** in worker-specific README or comments
8. **Keep workers focused** - each worker should have a single, clear purpose
```bash
cd apps/hello
pnpm run dev
curl http://localhost:8787
```
```bash
pnpm run lint
pnpm run format
pnpm run check
pnpm run test
pnpm run build
```
```bash
export TF_VAR_tf_state_postgres_conn_str="postgresql://..."
export TF_VAR_env="dev"
export TF_VAR_app_name="hello"
export TF_VAR_cloudflare_account_id="abc123"
cd deployment/modules/cloudflare/workers/hello
terragrunt apply
```
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/immich-workers-development-i0g7bl/raw