Skip to main content
Refract ships as a private GitHub repository you own as a collaborator. When new versions ship — new adapters, bug fixes, architectural improvements — you pull them in the same way you’d pull from any upstream remote. No forced upgrades, no breaking changes without warning.

​
How it works

When you purchased Refract, you were added as a collaborator with pull access to the private repository. Your project has two remotes:
  • origin — your own repository where your product lives
  • upstream — the Refract repository where updates come from
Updates flow one way: from upstream into your origin. You decide when to pull and how to handle conflicts.

​
Initial setup

If you haven’t added the upstream remote yet, do it once:
Verify both remotes are set up:
You should see both origin and upstream listed.

​
Pulling an update

When a new version ships, you’ll be notified in #announcements on Discord. Here’s how to pull it into your project:
  1. Fetch the latest from upstream:
  2. Check what’s changed:
  3. Merge into your branch:
  4. Resolve any conflicts (see Handling conflicts below).
  5. Verify everything still works:
Always run make test-all after merging an update. If tests pass, the merge is safe. If they don’t, the output will tell you exactly what broke.

​
Troubleshooting dependency errors after an update

If your fork is older and you just merged upstream, you can hit runtime dependency errors even when the merge itself is clean. Example:
This usually means your backend container is using a stale /app/node_modules volume that doesn’t include newly added or rebuilt workspace packages. Use this recovery flow from the repo root:
make deps-fix recreates backend/consumer runtime node_modules volumes (your database is preserved), refreshes workspace deps, reinstalls runtime deps sequentially, verifies consumer workspace symlinks, rebuilds workspace packages, and starts the full stack. If the error still persists, use the clean-slate reset:

​
Handling conflicts

Most updates won’t conflict with your code — Refract’s changes tend to happen in infrastructure and tooling files, while your product code lives in different areas. The files most likely to conflict: When in conflict, the rule is simple: keep your product logic, take Refract’s infrastructure improvements. If you’re unsure, paste the conflicting section in #help on Discord and I’ll tell you which side to take.
The smaller and more focused your changes to Refract’s core files, the fewer conflicts you’ll have. If you find yourself heavily modifying compose.yml or core configuration files, consider whether those changes belong in your product layer instead.

​
What updates include

Updates are announced in #announcements on Discord with a summary of what changed. They generally fall into these categories: New adapters — new providers for existing tools (e.g. a Resend mailer adapter, a new deployment strategy). These are additive — no conflicts expected. Bug fixes — fixes to existing behaviour. Usually safe to take wholesale. Architectural improvements — refinements to patterns, new abstractions, better TypeScript types. May require minor adjustments to code that extends those patterns. Breaking changes — rare, but when they happen they’ll be clearly marked in the announcement with a migration guide. Breaking changes are never shipped silently.

​
If you’ve diverged significantly

If you’ve been building for a while and the merge looks overwhelming, don’t panic. A few options: Cherry-pick specific commits — instead of merging everything, pick only the commits you want:
Ask for help — post in #help with your situation. If you’re on the Studio plan, this is exactly what the architecture call is for. Skip the update — you own the code. If an update doesn’t add value for your project right now, you don’t have to take it. Your existing codebase won’t break.

​
What’s next?

  • Support — Discord, bug reports, and how to reach me directly.
  • Getting started — back to the beginning if you need a fresh orientation.