Adding a sign-in option used to mean editing the sign-in code in each of our React apps. Every app kept its own copy, and no two copies were quite the same. Today we make the change once, in shared code, and every app picks it up on its next build.
Part one · The idea

Every new app started as a copy of the last
Needl.ai started with one web app. As the product grew, new capabilities arrived as their own React apps, such as our chat assistant, market intelligence and reporting apps. Separate apps let each team move at its own pace and ship without touching the rest.
The cost showed up slowly, in the basics most apps needed: sign-in, an API client, base UI components, data-fetching setup, mock data and settings. Each new app got them by copying them from the last one. Before long, most apps had their own copy of the same few dozen UI components.
Copies drift one reasonable change at a time
A UI bug got fixed in the app where it was reported. A library got upgraded in the app that needed its new feature. Every change made sense in its own app, and none of them reached the others. Over time the apps disagreed on library versions, lint rules and settings, and nobody had decided they should.
Before
After
One Bun workspace
Shared package
- one lockfile
- one settings folder
- one lint and type setup
- one local address
Illustrative. App names describe what each app does.
A fix should land once
We wanted a fix to shared code to land in one place, every app on the same version of each library, and new apps that work on day one, so the time goes into the app itself.
Everyday tasks got shorter
| Task | Before | Now |
|---|---|---|
| Add a sign-in provider | Change every app | One shared change, plus a setting |
| Change a setting every app uses | Edit each app's settings | Edit one file per environment |
| Give one app its own setting | Keep a separate settings folder | Add an app-specific entry to each environment's file |
| Fix a shared component | Fix it in each app that copied it | Fix it once |
| Upgrade a library | App by app, at different times | In one change across the apps, recorded in one lockfile |
| Build a screen before its API is ready | Copy mocks from another app | Mock the API and start |
| Start a new app | Copy the last app | Start from a template |
| Run several apps locally | Separate ports, broken links between apps | One command, one address |
Part two · The engineering

Why we chose Bun workspaces
We tried two smaller setups first, one with symlinks and one with npm workspaces. Both worked, so we judged them on what each would cost to maintain.
| Approach | Why it lost |
|---|---|
| Keep copying | The status quo, and the source of the drift. |
| Symlinks | Worked, but leaned on an operating-system feature rather than the package manager, and gave no help with dependency versions. |
| npm workspaces | Worked, but needed more custom dev-server and build setup than we wanted. |
| Version the shared code separately | Every app that uses it lives in one repository, so separate versions and releases would add work with no benefit. |
| Bun workspaces Chosen | Parts of our stack already ran on Bun, and it gave us one install and one lockfile with the least setup. |
The workspace itself is small. A root package.json lists the members and records the Bun version. Every app installs from one lockfile, the file that records the exact version of every dependency. We refuse installs from npm or Yarn, so nobody creates a second lockfile by accident.
{
"workspaces": ["shared", "app-a", "app-b", "app-c"],
"packageManager": "bun@<version>"
}The shared package ships as source
The apps compile the shared code as part of their own build. There is no separate build step for it, so an edit to a shared component shows up in every running app on the next hot reload.
Only what an app imports ships, mostly
A fair worry with one large shared package is that every app now ships all of it. Splitting it by area was one option, so first we looked at what the apps actually ship.
For most shared code, each app's bundle holds only what that app uses. That is tree-shaking, the build step that leaves out code an app never imports. The bundler starts from the app's own files, follows every import, and keeps only the modules those imports reach. Apps import shared code by its full path, so a component no file imports never reaches the bundle.
// app-a imports exactly the shared modules it needs
import { Button } from "shared/components/ui/button";
import { DataTable } from "shared/components/ui/table";
// the chart, upload and chat modules are never imported, so they never shipThe exception taught us the most. Tree-shaking drops modules nobody imports, but it keeps everything a used module imports. Our sign-in module imports every sign-in provider's library, and our branding module imports every brand's assets. An app that only ever uses one provider still ships the others. Tree-shaking handles the rest, so the shared code stays one package. The rule we took from the exception is to keep each module narrow, so that importing one thing doesn't pull in everything next to it.
| Module | What an app gets |
|---|---|
| Sign-in | Sign-in screens and the signed-in user |
| API client | One HTTP client with error handling and data-fetching setup |
| UI components | Base components such as buttons, dialogs, tables and forms, on one design system |
| Hooks | Reusable React hooks for common tasks, such as checking feature access, uploads and chat sessions |
| Providers | Data fetching, user identity and theme, wired once |
| Mocks | Sample API responses for local development |
| Branding | Colours, logos and type, set per organisation |
| Feature modules | Whole features that several apps share |
The shared package holds whole features as well as base components. Chat history, file uploads, data-source connections, usage pages and branded report exports are each built once and used by several apps.
Brand profiles are saved per organisation, and any app can switch to one without a rebuild.
Sign-in and data access come built in
An app gets sign-in by wrapping itself in the shared sign-in provider and adding a short page guard that the template writes for it. The guard sends anyone who isn't signed in to the sign-in screen. All the sign-in logic lives in the shared package.
<SignInProvider>
<DataProvider>
<ProtectedRoute>
<App />
</ProtectedRoute>
</DataProvider>
</SignInProvider>Data access works the same way. The app uses the shared API client and query hooks, so expired sessions, retries and caching behave the same in every app.
Signing out of one app signs you out of the others you have open, and after signing in you land back in the app you started from.
Supporting a new sign-in provider is one change to the shared sign-in code, plus a setting for each deployment that uses it. No app changes its own code, and every app can offer it from its next release.
Features can also be switched on per organisation. The apps check those switches in the same way, so gating a page is a single wrapper.
A mistake in sign-in locks people out, so we moved it in three steps that each shipped on its own.
- We moved the first sign-in pieces from one app into the shared package and tested them on staging. The other apps switched one at a time.
- Nearly three months later, we moved the remaining pieces and removed every app's leftover copy in one change, which deleted 2,264 lines across 113 files.
- Finally, we moved the sign-in screens themselves into shared code, so no product app carries its own.
Settings change in one place, and each app can differ
Each app used to carry its own folder of environment settings, and the folders had drifted. One had renamed a variable, another was missing an environment. Now every app that needs settings reads one shared folder, with one file per environment.
A setting that every app uses, such as the address of our API, is written once in each environment's file and reaches every app on its next build. A setting that only one app needs sits in the same file, under that app's name. A new environment gets one new settings file that every app shares, instead of a copy in each app.
export default defineConfig({
envDir: "../shared-settings", // one settings folder for every app
});# Shared by every app
VITE_API_URL=https://api.example.com
# Only for app A
VITE_BASE_PATH_APP_A=/app-a/Every app answers on one local address
Locally, every app used to run its own dev server, and some of them fought over the same ports. Links between apps broke when each ran on its own port. Now one command starts every app and a small Caddy reverse proxy, a server that takes every request on one address and forwards it to the right app by path.
Shared mocks cover the APIs every app calls, and each app adds its own. So we can build and review a screen before its API exists, and run an app locally with no backend.
:5100 {
handle /app-a/* { reverse_proxy localhost:5101 }
handle /app-b/* { reverse_proxy localhost:5102 }
}Each app builds alone
At first, a change to one app rebuilt every app. Splitting the Docker build into one stage per app fixed that. Builds now install dependencies once, then build each app in its own cached stage, so a change to one app doesn't rebuild the others.
In the production build, each app sees only the shared package and its own folder, so an import from one app into another fails there. Any change to the apps runs every app's type, lint and format checks and tests, and the checks also flag unused code in the apps.
Trade-offs and limits
- One lockfile shows every version, but doesn't force one. In one app, a shared notification component and the app's own code ended up on different major versions of the same library, so notifications never appeared. One clean-up took that kind of drift from ten libraries to zero. Keeping it there still takes a deliberate upgrade across the apps.
- Any change to the apps runs every app's checks. That costs CI time, and we accept it to catch problems before release.
- Shared code needs more care. A change to a shared component has to suit every app that uses it, so it is reviewed with all of them in mind.
- A shared package needs discipline. Code moves in only once a second app needs it. Otherwise the package fills up with code that only one app uses.
Spinning up a new app
Anyone on the team can ask our AI coding agent for a new app from one of our templates and get one with sign-in, the API client, query hooks and deployment already wired in. From there, they spend their time on the app rather than its plumbing.
There are two templates. The full template gives a new app our layout, theme and branding. The blank template gives it everything except the look, so the people building it have full control of the design.
Already in place
- Sign-in and sign-in-only pages
- The signed-in user and their organisation
- API client and data fetching
- Mock API layer with shared sample data
- Lint, type and test checks
- Build and local proxy setup
Left to the app
- Layout and navigation
- Styles, theme and branding
- Pages and features
- App-specific mocks
The blank template ships plain Tailwind with no theme, so the people building the app have full control of the design.
Even with a template, adding an app edits files outside its own folder. Figure 6 is the checklist we would hand to anyone building a workspace like ours.
| Where | What changes |
|---|---|
| Settings | A line in each environment's file |
| Workspace | The member list and the lockfile |
| Shared package | The new app's entry in a shared list |
| Build and checks | A build step, a CI job and the unused-code check |
| Backend | A route that serves the app |
| Local development | A proxy route and the start script |
Every move into the shared package leaves less for the next app to build.
FAQ
Do I need Bun to do this?
No. npm, pnpm and Yarn all support workspaces, and the same ideas apply.
How would I start this in my own repository?
Create the workspace with one app and one shared lint and type setup. Move one shared piece, such as the API client, and ship it. Then move apps across one at a time, and add a local proxy once you run several apps together.
Can an app skip a shared module?
Yes. Apps import each shared module by its own path, so an app can use its own table or theme instead.
Can a project outside the workspace use the shared package?
No. It ships as source and compiles inside each app's build, so only workspace members can use it.
Does a shared change reach apps that are already deployed?
Not until each app is built and deployed again, because every app compiles the shared code into its own build.
Talk to us about Needl.ai
See the product these apps power, or talk to us about how your team works.

One API Catalog, Many Audiences
From GPU Servers to Serverless: Reading 300 Pages in a Minute