- Docs
- Contributing
Development setup
How to run Thingport locally with hot reload, so you can work on it. If you just want to run an instance, follow the Docker Compose instructions in the README instead.
What’s in the repo
Section titled “What’s in the repo”| Directory | What it is |
|---|---|
backend/ | Express + Prisma API (TypeScript). Serves everything under /api/*. |
frontend/ | React + Vite single-page app. |
extension/ | “Thingport Grab” browser extension — TypeScript + SCSS, built with esbuild. |
bridge/ | Slicer bridge helper app (Go). |
docs/ | This documentation. |
Prerequisites
Section titled “Prerequisites”- Node.js 24 or newer. The root
.nvmrcsays 24 (nvm usepicks it up), and CI and the Docker images run on it. - Docker, to run Postgres. Everything else runs natively so you get hot reload.
- Go 1.21+ — only if you’re changing
bridge/.
1. Install dependencies
Section titled “1. Install dependencies”git clone https://github.com/TautvydasDerzinskas/Thingport.gitcd Thingport
npm install # root -- installs the husky pre-commit hooknpm --prefix backend cinpm --prefix frontend ciEach project has its own package-lock.json; there is no workspace root tying them together.
2. Start Postgres
Section titled “2. Start Postgres”The db service in docker-compose.yml has no host port mapping on purpose — it’s only
reachable from inside the Compose network, so a natively-run backend cannot connect to it. Run
your own container for development:
docker run -d --name thingport-db \ -e POSTGRES_USER=thingport \ -e POSTGRES_PASSWORD=thingport \ -e POSTGRES_DB=thingport_dev \ -p 5432:5432 \ postgres:16-alpineIf something already listens on 5432, map a different host port and adjust DATABASE_URL below.
3. Configure the backend
Section titled “3. Configure the backend”cp backend/.env.example backend/.envbackend/.env.example is written for the Docker Compose deployment, so two values must change
for local development:
| Variable | Set it to | Why |
|---|---|---|
DATABASE_URL | postgresql://thingport:thingport@localhost:5432/thingport_dev?schema=public | The example points at db:5432 — the Compose service hostname, which doesn’t resolve outside Docker. |
FILE_STORAGE | an absolute or relative path you own, e.g. ./storage | The example uses /app/storage, the path inside the container. |
Also set AUTH_SECRET to any non-empty random string — it signs login tokens, and the example
value is a placeholder.
Leave API_PORT=8000. The Vite dev server proxies /api to http://localhost:8000
(frontend/vite.config.js), so changing one means changing both.
backend/.env is gitignored. Never commit it.
4. Create the database schema
Section titled “4. Create the database schema”cd backendnpm run prisma:generate # required -- there is no postinstall hook, so the client isn't generated by `npm ci`npx prisma migrate deploy # applies the 27 committed migrations5. Run it
Section titled “5. Run it”In two terminals:
npm --prefix backend run dev # tsx watch -> http://localhost:8000npm --prefix frontend run dev # vite --host -> http://localhost:5173Open http://localhost:5173. The first account you register becomes the admin — see
backend/src/routes/auth.ts, which bootstraps the first user as ADMIN and everyone after as
MEMBER.
Run from the checkout, the backend offers the tools in its own tools folder under Administration →
Tools, not the repository’s on GitHub, and reads them afresh on each visit: change a tool, refresh, and Update
takes the change. The local docker-compose.yml mounts the folder for the same. See the tools guide
for using them, and tool development for writing one.
Optional: FlareSolverr
Section titled “Optional: FlareSolverr”FlareSolverr is an optional fallback for declared provider pages and API reads challenged by Cloudflare. Thingiverse and MyMiniFactory first use guarded direct transport; a 429 or challenge may retry through the solver with the API token in the URL. MakerWorld may send session cookies. The configured solver and its logs therefore receive credentials. Use a private, isolated solver: its browser redirects and third-party requests are outside Thingport’s per-hop destination guard, even though Thingport validates the initial destination.
Binary downloads, authenticated Cults3D calls and MakerWorld’s Bambu cloud API are unsupported. Cults3D’s solver routes cover public pages only.
docker run -d --name thingport-flaresolverr -p 127.0.0.1:8191:8191 ghcr.io/flaresolverr/flaresolverr:latestThen set its URL (http://localhost:8191, with or without /v1) in Administration → Connections →
FlareSolverr. FLARESOLVERR_URL in backend/.env is copied into that setting on the first startup; after that the
saved value wins and the env var is ignored. Configuring the URL enables fallback for all declared provider
routes; clearing it disables FlareSolverr globally, including cached page-proxy decisions.
Any http:// or https:// solver URL works by default, so existing LAN setups keep running. Set
FLARESOLVERR_REQUIRE_HTTPS=true to require HTTPS for remote solvers: HTTP is then allowed only for exact
flaresolverr, localhost, 127.0.0.1 or [::1] hosts, with an optional port, and saved settings and
FLARESOLVERR_URL cannot bypass it. System Health warns about a plaintext remote solver and suggests the variable
once the URL is secure. Solver requests and connection tests refuse endpoint redirects either way, so a proxy in front
of the solver has to answer /v1 itself: a 307 or 308, even just to /v1/, fails until the proxy is changed.
Provider manifests own solverRoutes: exact host, anchored path pattern, ordinary query names and any permitted
query credentials or cookies. The shared solver enforces HTTPS and those declarations; callers cannot request a
credential bypass. Keep API credentials on API-only routes and regenerate copies with npm run providers:sync.
See Provider development for the module contract.
Running the tests
Section titled “Running the tests”Backend
Section titled “Backend”19 test files, 151 tests. They run against a real Postgres database, registering accounts and creating and deleting rows as they go.
docker run -d --name thingport-test-db \ -e POSTGRES_USER=thingport -e POSTGRES_PASSWORD=thingport -e POSTGRES_DB=thingport_test \ -p 55432:5432 postgres:16-alpine
cd backendexport TEST_DB="postgresql://thingport:thingport@localhost:55432/thingport_test?schema=public"
DATABASE_URL="$TEST_DB" npx prisma migrate deployDATABASE_URL="$TEST_DB" npm testThe suite takes about 30 seconds. It runs test files sequentially on purpose — several files
mutate the same global Setting rows, and parallel workers race each other. See the comment in
backend/vitest.config.ts.
Frontend
Section titled “Frontend”npm run test:run in frontend/ runs the tests with Vitest, and npm run verify adds the type check, lint and build.
They run without a DOM: components are rendered to static markup and read as text (see
frontend/src/components/importQueue/testing.tsx).
Regression pack
Section titled “Regression pack”Playwright scenarios in regression/ that drive the real app in Chromium: sign-up, sign-in,
uploading (single and multiple files, zips, folder trees), the consume folder, the import queue, collections, and the
sidebar (navigation, the admin-only route, bookmarks and their drag-to-reorder, collapsing). Upload
fixtures are generated in tests/fixtures.ts rather than checked in. The consume folder is
regression/consume/, bind-mounted into the backend for the run. MakerWorld links import with no network:
fixtures/fake-provider.cjs, preloaded into the backend for the run, answers their calls, and the first digit of a
model’s id says whether it imports at once, waits for a test to let it go, or fails. run.sh builds the backend and
frontend images from your checkout, starts them with Postgres on port 8090, runs the scenarios, and
then removes the stack. The database and storage live on tmpfs, so every run starts empty and leaves nothing behind.
It never touches your development database. It needs Docker.
cd regressionnpm installnpx playwright install chromium./run.sh # whole pack./run.sh tests/models.spec.ts # extra arguments go to `playwright test`CI runs it every Saturday at 00:00 UTC (.github/workflows/regression.yml). You can also start it
from the Actions tab. When it fails, the HTML report, traces and container logs are uploaded as the
regression-report artifact.
App screenshots
Section titled “App screenshots”The README and website screenshots in frontend/src/assets/screenshots/ are captured from a running
instance with a populated library, by regression/screenshots.mjs (the extension’s screenshots
aren’t covered). It signs in, captures every shot in the light and the dark theme at 1400×790 and 2× scale,
and overwrites the files in light/ and dark/. The account’s theme, Categories/Folders choice and print profiles
layout are switched for the shots and restored afterwards, as are social features, which are on for the run so the
sidebar has Explore and Chats. A shot that can’t be taken is reported without stopping the run. The import queue’s rows,
Explore and who a collection is shared with are made up and answered in the browser, so nothing changes on the
instance.
cd regressionTHINGPORT_PASSWORD='…' npm run screenshots -- --url https://thingport.example --email you@example.com \ --model <id> --quality-model <id> --ai-description-model <id> --profiles-model <id> --license-model <id> \ --shared-collection <id>npm run screenshots -- --url … --email … --only 03,04 # just some shotsModels are named by id: one for the details and 3D preview shots, one whose print quality check found problems,
and one whose description AI rewrote (that shot is skipped without it). The customizer and collection sync shots
take the library’s first model with a script and first synced collection, unless --generative-model or
--synced-collection names another. The print profiles and licence shots need a model whose profiles and licence were
read, which happens the first time its owner opens it, and the sharing shot a collection to open the form on. The Open
adapted shot (56) uses the print profiles model too, with the account’s slicers and printers answered in the browser.
The connected-instances shots, 43-49, need two instances paired with each other, which a library instance usually
isn’t, so they’re taken from a demo pair: one at home connecting to one on the internet through a link. Take 43-45 and
48 on the home instance as its admin and 46, 47 and 49 on the other, 48 (--connect-to the other’s address) before
connecting and 49 before approving the request. For a pair on one machine under names it can’t resolve, such as
workshop.lan and makerspace.example behind a local proxy, --host-rules passes Chromium its
--host-resolver-rules, Node needs the same names mapped for the script’s own requests, and --no-blur keeps the
made-up handles, name@instance, which are what the shots show.
--out writes somewhere else instead, e.g. to compare before replacing. Self-signed certificates
are accepted.
Release notes pictures
Section titled “Release notes pictures”The What’s new pictures are a different set: cropped to the thing each one is about, WebP, and named after the
release. regression/release-shots.mjs captures them from a running instance into release-notes/screenshots/,
the same way, and skips the shots the instance has nothing for (no model with print profiles, no partner instance)
rather than failing the run. It holds the current release’s shots; earlier ones are in its git history.
cd regressionTHINGPORT_PASSWORD='…' npm run release-shots -- --url https://thingport.example --email you@example.com \ --profiles-model <id>npm run release-shots -- --url … --email … --only storage,providers # just some shotsA shot’s file is what an item’s images then names, so the two are written together — an item naming a picture
nothing captures leaves a gap in the dialog. Thingport Grab’s own pictures come from
npm --prefix extension run screenshots instead, and are converted to WebP by hand.
What the shots show has to be on the instance first: for 1.7.0’s, a MakerWorld model with print profiles, read already,
for the Open adapted shots. What a shot needs of the account that it may not have is answered in the browser: the
slicers and printers that make Open adapted name a printer, and badges while achievements are off. The script only
switches your theme and print profiles layout for the run, and restores them. Grab’s pictures, such as its Download
adapted, come from npm --prefix extension run screenshots -- --adapted and are converted with sharp.
Quality checks
Section titled “Quality checks”| Command | What it runs |
|---|---|
npm run format | Prettier, gofmt, prisma format |
npm run format:check | the same, check only (CI) |
npm --prefix backend run lint | oxlint |
npm --prefix frontend run lint | oxlint |
npm --prefix frontend run typecheck | tsc --noEmit |
npm --prefix frontend run verify | typecheck + lint + tests + build |
A husky pre-commit hook formats staged files and runs oxlint over whichever project you touched (see
lint-staged.config.js). It does not typecheck, so run typecheck yourself before pushing
frontend changes — CI will.
Extension
Section titled “Extension”cd extensionnpm installnpm run dev # watch build into dist/chrome (npm run dev:firefox for dist/firefox)- Chrome / Edge:
chrome://extensions-> enable Developer mode -> Load unpacked -> selectextension/dist/chrome. - Firefox:
about:debugging#/runtime/this-firefox-> Load Temporary Add-on -> selectextension/dist/firefox/manifest.json.
Reload the extension after each rebuild, and point it at http://localhost:5173 in the popup.
Chrome and Edge run the background bundle as a service worker while Firefox runs it as an event
page — if you add top-level code there, make sure it works in both. See
extension/CONTRIBUTING.md for the code layout, the per-browser
builds, the store zips and the screenshot generator.
Bridge
Section titled “Bridge”cd bridgego test ./...go run ./cmd/thingport-bridgemacOS URL-scheme handling uses Cocoa and needs cgo, so the macOS build only works on a Mac.
Windows and Linux binaries cross-compile with CGO_ENABLED=0.
System notifications
Section titled “System notifications”Announcements for every instance, such as a known bug or a new feature, live in
system-notifications.json at the repo root. Each backend fetches it
from main at startup and every 6 hours, and sends each entry once to each user it’s meant for, as an
ordinary notification (the System tab). To post one, add an entry to entries and merge it:
{ "entries": [ { "id": "2026-10-imports-fail-on-printables", "title": "Printables imports fail since Oct 10", "body": "Printables changed its API. A fix is on the way; update when it lands.", "url": "https://github.com/TautvydasDerzinskas/Thingport/issues/123", "published_at": "2026-10-11T12:00:00Z", "audience": "admins", "version": "<1.2.0" } ]}idmust be unique and never reused: it’s what stops an entry being sent twice.bodyandurlare optional;urlmust behttps://, and the notification shows its domain.pathis an optional in-app page opened on click, e.g./admin.published_atis the date shown; a future date waits until then.audienceisadmins(the default) orallfor every user.versionlimits it to instances on certain versions:1.2.0exactly, or<,<=,>,>=a version. Leave it out for all versions. An instance that later updates into the range still gets it.- Versions before 1.0.0 read only the
notificationslist and ignoreversion, so add there only what every one of them should get; everything else goes inentries. - Entries older than 90 days aren’t sent, so old ones can stay in the file or be removed.
SYSTEM_NOTIFICATIONS_URLpoints a backend at another file; an empty value turns fetching off.
An entry past those 90 days is spent: no instance will ever be sent it again. Move it to
system-notifications-archive.json, which nothing fetches, rather than
deleting it — the record of what was announced is worth keeping, and an id must never be reused. Until an entry
is that old, leave it where it is: an instance that has been off for a month still has it coming.
Release notes (What’s new)
Section titled “Release notes (What’s new)”The first time a backend starts on a newer version than it last ran, every user gets a notification that opens
the What’s new dialog (admins can reopen it from Update Checker in Administration). A fresh installation doesn’t get this notification. There’s no need to add a “Welcome to
X.Y.Z” entry to system-notifications.json for this any more.
The dialog fetches its content from main, so it can be written after the release is out (a dev backend reads
its own checkout instead, for previews, as described below):
release-notes/latest-release-notes.jsonwhen itsversionis the instance’s backend version.- Otherwise
release-notes/archive/<version>.json, the notes of an earlier release, for an instance still on it. - Otherwise
backend/CHANGELOG.mdfor that version, with thefrontend/CHANGELOG.mdrelease that went out with it. An instance that skipped versions gets every release since the one it ran before, up to five.
The dialog’s history button lists the earlier releases that have notes, the latest file’s when it’s behind and the
archive’s, and opens any of them in place of the ones it opened on, with Back to latest to return. The archive
needs no index: the backend asks for a file by each version in backend/CHANGELOG.md, and caches the misses.
To write the notes for a release, first copy the current file into
release-notes/archive/ under the version it names, so the release it describes isn’t
lost when the file is overwritten:
cp release-notes/latest-release-notes.json "release-notes/archive/$(node -p 'require("./release-notes/latest-release-notes.json").version').json"An archived file’s images stay relative to release-notes/, where they were read from, so name the file after the
version inside it: one that names another is never shown. Then replace the file’s contents:
{ "version": "1.2.0", "title": "Optional headline", "summary": "Optional sentence or two under it.", "contributors": ["octocat", "monalisa"], "items": [ { "type": "feature", "highlight": true, "title": "Pick an accent colour", "description": "Optional detail.", "code": "claude mcp add ...", "images": [{ "src": "screenshots/1.2.0-accent.webp", "caption": "Optional caption" }], "url": "https://github.com/TautvydasDerzinskas/Thingport/pull/123" } ]}typeisbreaking,feature,improvementorfix; the dialog groups them in that order.highlight: trueshows the item as a large card above the grouped list; keep it to the release’s headline features. The first feature among them is the release’s top feature, framed in gold.codeis a command shown in a box with a copy button, e.g. how to connect something.contributorsare the GitHub usernames of everyone who helped with the release, thanked in one box under the notes with their GitHub pictures, so items don’t need a thanks of their own. A name that isn’t a GitHub username is left out; credit the person behind a bot account rather than the bot.imagesare relative to the file (put them inrelease-notes/screenshots/, named after the version) or fullhttps://URLs; up to six per item. Crop them to the control being shown rather than the whole page; WebP keeps them small. Everything buttypeandtitleis optional.- Limits:
title200 characters,summaryanddescription2000,code1000, and 100contributors. One item past a limit fails the whole file, which then falls back to the changelog, so check the longest one-line fixes. - A file that doesn’t parse falls back to the changelog, as does one naming a version outside the running
release’s
x.yline. One naming an earlier patch of that line still counts, for the quiet hotfixes below. RELEASE_NOTES_URLpoints a backend at another copy of the repo files, or afile://URL at a checkout; an empty value turns fetching off. It’s also where the backend finds the newest Thingport Bridge (bridge/package.json), for the notification that tells someone theirs is out of date.
To preview the notes before they’re pushed, open What’s new on a backend started with npm run dev: it reads these
files from the checkout it runs in rather than from main, afresh each time, and shows the latest file under its own
version, whatever package.json names, with its pictures. A file that doesn’t parse falls back to the changelog as
it would for everyone, and the backend’s console says what’s wrong with it.
To update without telling anyone, e.g. a hotfix straight after a release, add its version to
release-notes/quiet-releases.json in the same release PR, so it’s on main
before instances update:
{ "versions": ["1.2.1"] }No notification is sent to an instance that already heard about the release the hotfix follows, and the next release’s
What’s new also covers what the quiet one changed. An instance further back is still told, so a quiet hotfix never
swallows notes nobody has seen: coming from 1.1.0 straight to 1.2.1 announces as usual, with What’s new starting at
1.1.0. Leave latest-release-notes.json naming 1.2.0 for this — a curated file is shown by a later patch of the same
x.y line, so those notes are what that instance reads. If the file can’t be read when an instance starts, the update
is announced as usual.
An entry can say where it is quiet from, which is its own x.y.0 by default:
{ "versions": [{ "version": "1.2.1", "quietFrom": "1.2.1" }] }quietFrom at the version itself keeps it quiet for everyone, however far back they are — as does listing an x.y.0,
which has no earlier release of its line to miss.
Related documents
Section titled “Related documents”- CONTRIBUTING.md — branch, commit and pull request workflow
- PROVIDER_SETUP.md — what each provider needs, with a setup page per provider under providers/
Feedback
Section titled “Feedback”Something unclear, wrong or missing on this page? Say so here, or react. It’s kept in GitHub Discussions. Something broken? Report it as a bug.