Skip to content

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.

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.
  • Node.js 24 or newer. The root .nvmrc says 24 (nvm use picks 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/.
Terminal window
git clone https://github.com/TautvydasDerzinskas/Thingport.git
cd Thingport
npm install # root -- installs the husky pre-commit hook
npm --prefix backend ci
npm --prefix frontend ci

Each project has its own package-lock.json; there is no workspace root tying them together.

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:

Terminal window
docker run -d --name thingport-db \
-e POSTGRES_USER=thingport \
-e POSTGRES_PASSWORD=thingport \
-e POSTGRES_DB=thingport_dev \
-p 5432:5432 \
postgres:16-alpine

If something already listens on 5432, map a different host port and adjust DATABASE_URL below.

Terminal window
cp backend/.env.example backend/.env

backend/.env.example is written for the Docker Compose deployment, so two values must change for local development:

Variable Set it to Why
DATABASE_URLpostgresql://thingport:thingport@localhost:5432/thingport_dev?schema=publicThe example points at db:5432 — the Compose service hostname, which doesn’t resolve outside Docker.
FILE_STORAGEan absolute or relative path you own, e.g. ./storageThe 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.

Terminal window
cd backend
npm 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 migrations

In two terminals:

Terminal window
npm --prefix backend run dev # tsx watch -> http://localhost:8000
npm --prefix frontend run dev # vite --host -> http://localhost:5173

Open 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.

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.

Terminal window
docker run -d --name thingport-flaresolverr -p 127.0.0.1:8191:8191 ghcr.io/flaresolverr/flaresolverr:latest

Then 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.

19 test files, 151 tests. They run against a real Postgres database, registering accounts and creating and deleting rows as they go.

Terminal window
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 backend
export TEST_DB="postgresql://thingport:thingport@localhost:55432/thingport_test?schema=public"
DATABASE_URL="$TEST_DB" npx prisma migrate deploy
DATABASE_URL="$TEST_DB" npm test

The 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.

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).

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.

Terminal window
cd regression
npm install
npx 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.

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.

Terminal window
cd regression
THINGPORT_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 shots

Models 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.

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.

Terminal window
cd regression
THINGPORT_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 shots

A 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.

Command What it runs
npm run formatPrettier, gofmt, prisma format
npm run format:checkthe same, check only (CI)
npm --prefix backend run lintoxlint
npm --prefix frontend run lintoxlint
npm --prefix frontend run typechecktsc --noEmit
npm --prefix frontend run verifytypecheck + 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.

Terminal window
cd extension
npm install
npm run dev # watch build into dist/chrome (npm run dev:firefox for dist/firefox)
  • Chrome / Edge: chrome://extensions -> enable Developer mode -> Load unpacked -> select extension/dist/chrome.
  • Firefox: about:debugging#/runtime/this-firefox -> Load Temporary Add-on -> select extension/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.

Terminal window
cd bridge
go test ./...
go run ./cmd/thingport-bridge

macOS 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.

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"
}
]
}
  • id must be unique and never reused: it’s what stops an entry being sent twice.
  • body and url are optional; url must be https://, and the notification shows its domain.
  • path is an optional in-app page opened on click, e.g. /admin.
  • published_at is the date shown; a future date waits until then.
  • audience is admins (the default) or all for every user.
  • version limits it to instances on certain versions: 1.2.0 exactly, 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 notifications list and ignore version, so add there only what every one of them should get; everything else goes in entries.
  • Entries older than 90 days aren’t sent, so old ones can stay in the file or be removed.
  • SYSTEM_NOTIFICATIONS_URL points 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.

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):

  1. release-notes/latest-release-notes.json when its version is the instance’s backend version.
  2. Otherwise release-notes/archive/<version>.json, the notes of an earlier release, for an instance still on it.
  3. Otherwise backend/CHANGELOG.md for that version, with the frontend/CHANGELOG.md release 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:

Terminal window
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"
}
]
}
  • type is breaking, feature, improvement or fix; the dialog groups them in that order.
  • highlight: true shows 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.
  • code is a command shown in a box with a copy button, e.g. how to connect something.
  • contributors are 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.
  • images are relative to the file (put them in release-notes/screenshots/, named after the version) or full https:// URLs; up to six per item. Crop them to the control being shown rather than the whole page; WebP keeps them small. Everything but type and title is optional.
  • Limits: title 200 characters, summary and description 2000, code 1000, and 100 contributors. 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.y line. One naming an earlier patch of that line still counts, for the quiet hotfixes below.
  • RELEASE_NOTES_URL points a backend at another copy of the repo files, or a file:// 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.

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.