Build Full-Stack Apps on Puter with Dynamic Workers
On this page
We added dynamic workers to Puter. Put your backend code in a __workers folder inside your website, publish the site on Puter, and the workers go online with it at the site's own address.
Serverless Workers already let you add backend endpoints to your app, so it can save shared data and run code on a server. But a worker was deployed separately from the site that used it. It had its own deploy step and its own *.puter.work subdomain, and you kept the site and the worker in sync by hand. With dynamic workers, the backend is a file in the site's folder, so the two deploy together.
Add a Worker to Your Site
Build your website as you normally would. Then create a folder named __workers next to your index.html, and add a file ending in .worker.js for each worker:
my-site/
index.html
style.css
__workers/
api.worker.js -> /__workers/api/...
matchmaking.worker.js -> /__workers/matchmaking/...
The name before .worker.js becomes the worker's path in the URL, and it can use lowercase letters, numbers, -, and _. Only files directly inside __workers are deployed. Files in subfolders, and anything that doesn't end in .worker.js (a helpers.js or a README), are ignored.
Nothing under __workers is served to visitors. Opening /__workers/api.worker.js in a browser returns a 404, so the worker file is a safe place for values the browser shouldn't see.
Write the Worker
Dynamic workers use the same router API and globals as any other Puter worker:
// __workers/api.worker.js
router.get("/health", async () => {
return { ok: true };
});
router.post("/scores/:game", async ({ request, params }) => {
const body = await request.json();
await me.puter.kv.set(`score:${params.game}:${body.player}`, body.score);
return { saved: true };
});
Everything works the same way they do in a regular worker. Inside the worker, me.puter is Puter.js signed in to your account as the site owner, so the scores above are saved in your key-value store and every visitor reads and writes the same data.
The data belongs to the site's address. If you publish the same files under a different subdomain, the workers there start with an empty store.
Call It From Your Site
Each worker answers at this URL:
https://<site>.puter.site/__workers/<worker>/<path>
The /__workers/<worker> prefix is removed before the request reaches your routes, and query strings are kept:
| Request | Route that runs |
|---|---|
/__workers/api |
/ |
/__workers/api/health |
/health |
/__workers/api/scores/chess?top=10 |
/scores/chess?top=10 |
Because the worker is on the same address as the page, the page can call it with a relative path:
const res = await fetch('/__workers/api/scores/chess', {
method: 'POST',
body: JSON.stringify({ player: 'alice', score: 1200 }),
});
const data = await res.json();
console.log(data); // { saved: true }
The path is the same on every primary puter.site host, so this code keeps working if you publish the site under another *.puter.site subdomain.
Update the Code
To change a worker, publish the site again with the new file. Requests run the new code shortly after, and the first request after a change can take a few seconds longer than the ones after it.
Dynamic Workers vs. Serverless Workers
| Serverless Workers | Dynamic Workers | |
|---|---|---|
| Where the code lives | Deployed separately from the site | A file in the site's __workers folder |
| How it deploys | Its own deploy step | With the site, when you publish it |
| URL | Its own *.puter.work subdomain |
/__workers/<name>/ on the site's address |
If your site is hosted outside Puter, or on a custom domain, a regular serverless worker is still the way to add a backend to it.
Get Started Now
- Create a
__workersfolder next to your site'sindex.html. - Add a
.worker.jsfile with your routes. - Publish the site the way you already do, with Publish as Website on puter.com,
puter site deployfrom the Puter CLI, or the GitHub Action.
With dynamic workers, your frontend and backend live in one folder and deploy together, so you can build a full-stack app on Puter without managing a server. Read the Dynamic Workers documentation to learn more.
Related
Ship a Full-Stack App with One Prompt
Create a to-do list app using Puter.js
Coding manually? see the guide