Skip to main content
skill CX Codex

linear-local-first-architecture — Claude Code skill: setup and use

linear-local-first-architecture tells the agent how to build a web app that answers instantly: workspace in IndexedDB, edits applied locally, sync queued in the background.

Apache-2.0 201 installs ★ 484 updated 2026-08-15

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add boraoztunc/skills --skill linear-local-first-architecture -a claude-code
Open on GitHub

What linear-local-first-architecture does

The skill lands in the agent as a set of principles. Treat the network as the bottleneck and read from local state instead of the API. Keep the whole workspace in IndexedDB and hydrate it into an observable graph in memory, MobX in the examples. An edit touches the local object first (issue.title, then issue.save()), and the sync engine batches the transaction later. Session checks run after the first render, so cached data paints right away.

Tactics come with stack specifics. Without a custom sync engine the skill points to SWR or Tanstack Query and their mutate call. Bundling is shown on Vite: target: "esnext" plus manualChunks that gives every node_modules package its own file, so a library bump invalidates one chunk. Critical chunks are declared in <head> with <link rel=modulepreload> to kill the fetch-parse-fetch chain. A service worker precaches the remaining route chunks after the first load.

The samples assume React, Vite and MobX: react() sits in the config, the store is a MobX observable. Move to another stack and the code needs rewriting, the principles do not.

What it helps with

  • drop loading spinners from the issue list
  • apply edits before the server answers
  • keep the workspace in IndexedDB and read from memory
  • split the bundle per package for fine-grained cache invalidation
  • preload critical chunks in parallel with modulepreload

Example prompts for the agent

  • Design a local store on IndexedDB so the task list renders without a spinner
  • Switch the issue save to an optimistic mutation with mutate from SWR
  • Configure manualChunks in vite.config.ts so each package ships as its own chunk

How to install linear-local-first-architecture

1Skills CLI (Vercel)

npx skills add boraoztunc/skills --skill linear-local-first-architecture -a claude-code

2Manually: put the files in place

~/.claude/skills/linear-local-first-architecture/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/linear-local-first-architecture/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about linear-local-first-architecture

How do I install linear-local-first-architecture in Claude Code?

Run npx skills add boraoztunc/skills --skill linear-local-first-architecture -a claude-code. The skill file ends up at ~/.claude/skills/linear-local-first-architecture/SKILL.md.

What does this skill do?

It gives the agent a local-first blueprint: reads from IndexedDB, optimistic writes, background sync, and a bundle split per package.

Do I need to write a sync engine?

No. SWR or Tanstack Query cover optimistic updates; a custom engine only matters if you want batched transactions like Linear.

Source text

SKILL.md · Apache-2.0
---
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 `<head>`:

```html
<script type=module crossorigin
  src="https://static.linear.app/client/assets/html.2_JBQs3Q.js"></script>
<link rel=modulepreload crossorigin
  href="https://static.linear.app/client/assets/vendor-mobx.Crhy2qQc.js">
<link rel=modulepreload crossorigin
  href="https://static.linear.app/client/assets/SyncWebSocket.Djw6l_Op.js">
<link rel=modulepreload crossorigin
  href="https://static.linear.app/client/assets/DatabaseManager.DKssGAN8.js">
<!-- ...around many more -->
```

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
<style>
  :root {
    --bg-color: #f5f5f5;
    --bg-base-color: #fcfcfd;
    --bg-border-color: #e0e0e0;
    --sidebar-width: 244px;
  }
  html { background: var(--bg-color); height: 100%; }
  body { font-family: "Inter Variable", Arial, Helvetica, sans-serif; }

  #appBorders {
    border: 1px solid var(--bg-border-color);
    background: var(--bg-base-color);
    margin: 8px 8px 8px var(--sidebar-width);
    border-radius: 12px;
  }

  #logo { transform: translateZ(0); }

  @keyframes logoBackgroundPulse {
    0%   { opacity: 0; transform: scale(0.8); }
    70%  { opacity: 1; }
    100% { opacity: 0; transform: scale(1.0); }
  }
</style>
<script>performance.mark("appStart");</script>
```

Inline JavaScript restores last-known shell tokens (sidebar bg, width, dark mode) before paint:

```javascript
<script>
// Electron context — lets CSS branch on native chrome.
if (navigator.userAgent.includes("Electron") && navigator.userAgent.includes("Linear")) document.documentElement.classList.add("electron");

// No local store → no workspace data → render the auth layout.
if (localStorage.getItem("ApplicationStore") === null) document.documentElement.classList.add("logged-out");

// Restore last-known shell tokens (sidebar bg, width, dark mode) before paint.
const c = JSON.parse(localStorage.getItem("splashScreenConfig") || "{}");
if (c.bgSidebarColor) document.documentElement.style.setProperty("--bg-sidebar-color", c.bgSidebarColor);
if (c.sidebarWidth) document.documentElement.style.setProperty("--sidebar-width", c.sidebarWidth + "px");
if (c.darkMode) document.documentElement.classList.add("dark");

// Compact sidebar to a sliver when the user opens links in the desktop app.
if (JSON.parse(localStorage.getItem("userSettings") || "{}").openLinksInDesktop) document.documentElement.style.setProperty("--sidebar-width", "8px");

</script>
```

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
<!-- in <head> of index.html -->
<link rel="preload"
      href="https://static.linear.app/fonts/InterVariable.woff2?v=4.1"
      as="font" type="font/woff2" crossorigin="anonymous">
<link rel="preconnect" href="https://static.linear.app" crossorigin>
```

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

© boraoztunc · Apache-2.0 · boraoztunc/skills

Similar skills

All skills for Frontend and UI →

From the same set22

The whole set →
waapi waapi instructs agents to write deterministic Web Animations API code for HyperFrames without relying on heavy external animation engines. CX Codex +1 211installs contribute-catalog The contribute-catalog skill guides a new HyperFrames block or component from an idea to an upstream catalog PR. Use it for captions, VFX, transitions, and lower thirds. CX Codex +1 211installs three Keeps a Three.js scene in HyperFrames tied to composition time: the adapter fires hf-seek and the scene draws the frame requested. CX Codex +1 209installs typegpu Skill for building GPU compositions with TypeGPU and WebGPU in HyperFrames: WGSL fragment shaders, compute pipelines, liquid glass effects, and particles on canvas. CX Codex +1 207installs conductor-rewrite-performance conductor-rewrite-performance optimizes React performance in local-first Tauri desktop apps. Stops cascading re-renders on route changes and cleans up sluggish streaming lists. CX Codex +1 186installs minimal-zine-poster minimal-zine-poster turns a theme, phrase, object, or photo into a prompt for a sparse zine-style poster, then generates the image. Use it for essay or newsletter cover art. CX Codex +1 126installs tailwind-v4 tailwind-v4 — a skill for Claude Code and other AI platforms that automates Tailwind CSS v4 migration, configuration, and debugging. Runs during styling tasks or framework upgrades. CX Codex +1 125installs visual-style-presets The visual-style-presets Claude Code skill selects and applies a visual direction to a website, landing page, dashboard, or app shell. It activates when a request names a look or asks for a coherent design direction. CX Codex +1 123installs

Project sponsors

Companies that keep this analytics open