---
name: linear-local-first-architecture
description: "Use when building a web app that must feel instant, when users complain about spinners or perceived slowness despite acceptable latency, or when designing a local-first sync architecture with optimistic updates."
---
## When to use this skill
- You're building a productivity tool where perceived speed is critical to user experience
- Users report the app "feels slow" despite reasonable network latency
- You need to eliminate loading spinners and skeleton states from user workflows
- You're architecting a local-first application with offline capabilities
- You want to implement optimistic updates that feel instant
- You're designing a keyboard-first interface for power users
## Core principles
1. **The network is the bottleneck—eliminate it wherever possible.** Every network request costs hundreds of milliseconds; the best optimization is to avoid the request entirely by reading from local state.
2. **Treat the browser as the database for each user.** Store the full workspace in IndexedDB and hydrate into an in-memory observable graph; the UI reads from local state, not the server.
3. **Mutations apply locally first, sync asynchronously.** Update the local observable immediately so the UI re-renders synchronously, then queue the transaction for background sync to the server.
4. **Render first, authenticate second.** If local data exists, render it immediately and verify the session in the background; only redirect to login if the server rejects.
5. **Ship less code in more pieces.** Aggressive code splitting, modern-only targets, and per-package vendor chunks reduce initial payload and improve cache granularity.
6. **Animate only composited properties.** Restrict animations to `transform` and `opacity` to keep work on the GPU; never animate layout-triggering properties like `width`, `height`, or `margin`.
## Tactics
### Set up local-first data architecture
Store the workspace in IndexedDB and hydrate into an in-memory observable store (MobX in Linear's case). The UI queries the local store, not the server.
```typescript
// A traditional web app updating the server
async function updateIssue({ issue }) {
showSpinner();
const response = await fetch(`/api/issues/${issue.id}`, {
method: "PATCH",
body: JSON.stringify({ title: issue.title }),
});
const updated = await response.json();
setIssue(updated)
hideSpinner();
}
// vs Linear
issue.title = "Faster app launch";
issue.save();
```
The first line updates an in-memory datastore (MobX observable). The second line queues a transaction that the sync engine batches and flushes to the server. The UI re-renders synchronously off the local update—no spinners, no waiting.
### Implement optimistic updates with standard libraries
If you're not building a custom sync engine, use libraries like Tanstack Query or SWR with optimistic updates:
```typescript
// optimistic mutation with SWR
mutate(
`/api/issues/${issue.id}`,
{ ...issue, title: "Faster app launch" },
false
);
// vs Linear
issue.title = "Faster app launch";
issue.save();
```
The key: UI responsiveness should not depend on network latency. Users perceive speed based on how quickly the interface reacts, not how quickly the server responds.
### Reduce bundle size with modern-only builds
Target only modern browsers, drop legacy polyfills, and use aggressive code splitting:
```typescript
// vite.config.ts (reconstruction; matches observed chunk graph)
export default defineConfig({
plugins: [react()],
build: {
target: "esnext", // no legacy syntax, no polyfills
cssMinify: "lightningcss",
modulePreload: { polyfill: false },
rollupOptions: {
output: {
// One chunk per npm package > ~3 KB. Cache invalidation
// becomes per-library instead of per-app-revision.
manualChunks(id) {
if (id.includes("node_modules")) {
const pkg = id.match(/node_modules\/([^/]+)/)?.[1];
if (pkg) return `vendor-${pkg}`;
}
},
},
},
},
});
```
Split every npm package into its own chunk. A traditional `vendor.js` invalidates the entire dependency graph on any bump; per-package chunking makes cache invalidation fine-grained.
### Preload critical chunks in parallel
Eliminate the waterfall of fetch → parse → fetch imports by declaring all critical chunks in ``:
```html
```
The `crossorigin` attribute on each preload matches the `crossorigin` on the entry script, so the browser reuses the cached fetch. The cold-load timeline collapses from a sequential waterfall into a single parallel batch.
### Precache remaining assets with a service worker
After the first page load, use a service worker to precache route-level chunks in the background:
```javascript
// The service worker has a precache manifest baked into its source,
// around 1,200 hashed assets covering route chunks, icons, and fonts.
// It pulls them down lazily after the first page load.
```
Within seconds of hitting the login screen, the full app sits in cache. Subsequent navigations skip the network entirely; the service worker answers directly from cache. Combined with IndexedDB, the app works offline.
### Inline critical CSS and boot logic
Avoid an external stylesheet fetch by inlining just enough CSS to paint the loading state:
```css
```
Inline JavaScript restores last-known shell tokens (sidebar bg, width, dark mode) before paint:
```javascript
```
By the time the first JavaScript bundle arrives, the loading screen is already correctly themed, sized, and positioned.
### Optimize font loading
Preload variable fonts with correct CORS mode to avoid double-fetching:
```html
```
```css
@font-face {
font-family: "Inter Variable";
font-weight: 100 900;
font-display: swap;
src: url(https://static.linear.app/fonts/InterVariable.woff2?v=4.1)
format("woff2");
}
/* Italic and Berkeley Mono follow the same shape, single woff2 each. */
```
Variable fonts cover the full 100–900 weight axis in a single woff2. `font-display: swap` renders the fallback stack immediately and swaps to Inter when it loads. `crossorigin="anonymous"` on the preload makes the browser reuse the cached font when CSS references it.
### Assume authentication, verify in background
Instead of blocking on session validation, check if local data exists:
```javascript
if (localStorage.getItem("ApplicationStore") === null) {
document.documentElement.classList.add("logged-out");
}
```
If `ApplicationStore` exists, the user has used the app before and their workspace is in IndexedDB. Render it immediately. The actual session token sits in a cookie; let the next request (WebSocket handshake, sync delta, any HTTP call) fail with a 401 if the session is stale, then redirect to login.
The flow is "do we have anything to show you," not "do you have a valid session."
### Use granular observables for surgical re-renders
Make every property on every model its own observable. When a delta arrives from the server, write to the corresponding observable. The framework (MobX) knows exactly which components depend on which fields and re-renders only those components.
A change that updates one field of one issue re-renders exactly the components that read that field—not the parent list, not the sidebar, one cell. A 50-issue update is 50 cell re-renders, not a list re-render.
### Design for keyboard-first interaction
Every common action should have a shortcut. Single letters edit the focused issue. Two-letter combos navigate. Modifiers act globally. Make shortcuts visible everywhere in the UI.
Implement a global command palette (`⌘ k`) that searches over actions, issues, projects, labels, status changes, navigation, settings. Search runs against the local MobX object pool—no server request, instant results.
### Animate only composited properties
Browsers have three tiers of property changes:
- **Composited properties** (`transform`, `opacity`): GPU-accelerated, independent of main thread
- **Paint-triggering properties** (`color`, `background-color`, `border-color`, `fill`): skip layout but redraw pixels
- **Layout-triggering properties** (`width`, `height`, `top`, `left`, `margin`, `padding`): force recomputation of every subsequent element
Never animate layout-triggering properties:
```css
/* What Linear does */
.row:hover {
background-color: var(--color-bg-hover);
transition: background-color 0.12s;
}
.icon-arrow {
transform: translateX(0);
transition: transform 0.15s;
}
/* What you'd write if you didn't know better */
.row:hover {
margin-left: 2px; /* triggers layout for every row beneath */
transition: all 0.2s; /* and now you're animating margin */
}
```
### Keep animation durations short
Default to shorter transitions than industry norms:
```css
/* variables form Linear's stylesheet */
--speed-highlightFadeIn: 0s;
--speed-highlightFadeOut: .15s;
--speed-quickTransition: .1s;
--speed-regularTransition: .25s;
--speed-slowTransition: .35s;
```
Use asymmetric timing: appear instantly when summoned, fade out over 150ms when dismissed. This makes the interface feel responsive to user intent.
## Anti-patterns
❌ **Don't wait for network requests before updating the UI.** Apply mutations locally first, sync in the background, and rollback only if the server rejects.
❌ **Don't animate layout-triggering properties** like `width`, `height`, `margin`, `padding`, `top`, or `left`. Stick to `transform` and `opacity`.
❌ **Don't block initial render on authentication.** If local data exists, render it immediately and verify the session asynchronously.
❌ **Don't bundle all vendor code into a single chunk.** Split each npm package into its own chunk so cache invalidation is per-library, not per-app-revision.
❌ **Don't use long animation durations (>250ms) for frequent interactions.** Shorter transitions make the app feel faster; reserve longer durations for infrequent, high-impact moments.
❌ **Don't fetch data on every navigation if it's already local.** Hydrate from IndexedDB on boot, lazy-load heavy tables on demand, and treat the server as a sync target, not a source of truth for the UI.
## Source
[How's Linear so fast? A technical breakdown](https://performance.dev/how-is-linear-so-fast-a-technical-breakdown)