Skip to content

Commit b7065d2

Browse files
harshagarwalnyukodiakhq[bot]autofix-ci[bot]amirhhashemi
authored
docs(solidstart): add cron jobs guide using Nitro Tasks API (#1534)
* docs(solidstart): add cron jobs guide using Nitro Tasks API Documents how to set up scheduled background tasks in SolidStart using Nitro's Tasks API. Covers configuration in app.config.ts, task file structure in tasks/ directory, and manual triggering via the Nitro task endpoint. Closes #964 * docs: address copilot review on cron jobs guide - Add caution block warning that /_nitro/tasks/* is publicly accessible in production (node-server, bun, deno-server) and should be protected - Add curl example with explicit GET method for task triggering * docs(solidstart): address review on background tasks guide Rework the SolidStart tasks guide per maintainer review: - rename guide to Background tasks (Nitro calls them tasks, not all are cron) - expand intro and link Nitro platform-support docs instead of hardcoding presets - mark tasks as experimental and split scheduling into its own section - use a practical cleanup-sessions example with package-install-dev - remove the production caution: /_nitro/tasks is a dev-server-only endpoint (registered solely in the _nitro-dev preset via dev-tasks.ts), not exposed by node-server/bun/deno-server presets * ci: apply automated fixes * format * Remove unused import --------- Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com> Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com> Co-authored-by: Amir Hossein Hashemi <87268103+amirhhashemi@users.noreply.github.com>
1 parent 3b13fb1 commit b7065d2

1 file changed

Lines changed: 115 additions & 0 deletions

File tree

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
---
2+
title: Background tasks
3+
use_cases: >-
4+
background tasks, scheduled jobs, periodic jobs, cron, automation
5+
tags:
6+
- cron
7+
- nitro
8+
- tasks
9+
- solidstart
10+
version: "1.0"
11+
description: >-
12+
Schedule background tasks in SolidStart using Nitro's Tasks API for periodic
13+
jobs and automated server-side operations.
14+
---
15+
16+
SolidStart supports scheduled background tasks through [Nitro's Tasks API](https://nitro.build/guide/tasks).
17+
Background tasks are server-side operations that run independently of the user request-response cycle.
18+
They are typically used for time-consuming or periodic work like data processing or maintenance jobs.
19+
These tasks execute on the server and can be triggered on a schedule or programmatically.
20+
21+
For details on which hosting platforms support scheduled tasks (including platform-specific native integrations like Cloudflare Cron Triggers and Vercel Cron Jobs), see the [Nitro documentation on platform support](https://nitro.build/docs/tasks#platform-support).
22+
23+
## Configuration
24+
25+
Tasks are an experimental feature and must be explicitly enabled:
26+
27+
```ts title="app.config.ts"
28+
import { defineConfig } from "@solidjs/start/config";
29+
30+
export default defineConfig({
31+
server: {
32+
experimental: {
33+
tasks: true,
34+
},
35+
},
36+
});
37+
```
38+
39+
## Creating a task
40+
41+
To create a task:
42+
43+
1. Create a task file in the `tasks/` directory at your project root (not inside `src/`).
44+
2. Use the `defineTask` function to define a task and `export default` the result.
45+
46+
```ts title="tasks/cleanup-sessions.ts"
47+
import { defineTask } from "nitropack/runtime";
48+
49+
export default defineTask({
50+
meta: {
51+
name: "cleanup-sessions",
52+
description: "Remove stale database sessions",
53+
},
54+
async run() {
55+
// Delete expired sessions older than 7 days
56+
const deletedSessions = await db.session.deleteMany({
57+
where: {
58+
lastActive: {
59+
lt: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000),
60+
},
61+
},
62+
});
63+
console.log(`Cleanup complete: ${deletedSessions.count} sessions deleted`);
64+
return { result: { deletedSessions } };
65+
},
66+
});
67+
```
68+
69+
:::note
70+
`nitropack` is a transitive dependency of SolidStart.
71+
If TypeScript can't resolve the import, add it as a dev dependency:
72+
73+
```package-install-dev
74+
nitropack
75+
```
76+
77+
:::
78+
79+
Refer to the [Nitro documentation](https://nitro.build/docs/tasks#task-interface) to learn more about `defineTask`.
80+
81+
## Scheduling tasks
82+
83+
To run a task automatically on a schedule, add a `scheduledTasks` object to your `app.config.ts`.
84+
The key is a cron expression, and the value is the task name or an array of task names.
85+
When multiple tasks are assigned to the same cron expression, they run in parallel.
86+
87+
```ts title="app.config.ts"
88+
import { defineConfig } from "@solidjs/start/config";
89+
90+
export default defineConfig({
91+
server: {
92+
experimental: {
93+
tasks: true,
94+
},
95+
scheduledTasks: {
96+
// Run at midnight every day
97+
"0 0 * * *": "cleanup-sessions",
98+
},
99+
},
100+
});
101+
```
102+
103+
:::tip
104+
You can use [crontab.guru](https://crontab.guru/) to help generate and understand cron patterns.
105+
:::
106+
107+
## Running tasks on demand
108+
109+
You can trigger a task manually via the Nitro task endpoint during development using a `GET` request:
110+
111+
```sh
112+
curl http://localhost:3000/_nitro/tasks/cleanup-sessions
113+
```
114+
115+
This is useful for testing your task logic without waiting for the scheduled time.

0 commit comments

Comments
 (0)