Local-first pain points

README.md

Local-first DX kinda sucks

These are not even all of my core pain points.

Is local-first development is really like this? Or can be attributed simply to a "skill-issue".

I haven't even touched other stuff like:

• CommonJS vs. ESM is still a predominant issue.
• ts-config is diabolical.
• building with different alternative node runtimes like bun, deno or Cloudflare wrangler is challenging.
• the most stable env. for me has been pnpm + vite.
• for lib development, what has been more stable and fast for me was this combo bun + vite.

vite.config-caching.js

// vite.config.js
// Problem 2: Vite Aggressively Caches The Wrong Stuff
import { defineConfig } from "vite";

export default defineConfig({
  cacheDir: "node_modules/.vite",
  
  optimizeDeps: {
    force: true, // Supposed to rebuild... doesn't
    include: ["@my/local-lib"] // Gets stuck on old version
  }
});

// The "fix" that shouldn't be necessary:
// rm -rf node_modules/.vite && vite --force

// Even worse with file: dependencies:
// package.json: "@my/local-lib": "file:../local-lib"
// Vite caches the symlink resolution, not the actual files

vite.config-local-hr.js

// vite.config.js
// Problem 1: Local Package Changes Will Not Hot Reload
import { defineConfig } from "vite";
import path from "path";

export default defineConfig({
  resolve: {
    alias: {
      "@my/local-lib": path.resolve("../local-lib/src/index.js")
    }
  },
  
  server: {
    watch: {
      // This SHOULD work but doesn't reliably
      ignored: ["!**/node_modules/@my/local-lib/**"]
    }
  },
  
  optimizeDeps: {
    exclude: ["@my/local-lib"], // Prevents pre-bundling
    // But also breaks hot reload
  }
});

// Reality: Edit local-lib → Nothing happens
// Required: Kill server → Clear node_modules/.vite → Restart → Hope 4 the best.

And just to comment in general about your post. Yeah, I agree. It's a mindfield and requires so much knowledge across so many different libraries to get things to work. Development is so fragmented. I think the bulk of the issues can be attributed to bundling and compiling. Introducing ESM and TypeScript introduces a lot of overhead, but both are offer nicer developer experiences once you're set up is working for you. These days when I create a project I use AI to do most of that stuff. I understand it a bit better but only through watching AI correct it, and investigating it. One technique I've found that works really well for me, is to tell Cursor to create a test file once it's finished and if the test doesn't pass I ask it to keep investigating the issue until it's fixed.