How one import shipped my database driver to the browser (132 kB vs 10 kB)

by Chanan Braunstein, Owner

TripEagle's People tab is where a planner invites people to a trip. When we added join links to it, its client chunk came out at 132 kB. Every other route's was between four and ten.

Nothing failed. It built, it typechecked, and its tests passed. A code review caught it, and the fix was one line: the chunk went to 9.71 kB.

This post is about that line: how one import can carry a whole module graph into the browser, why a type import doesn't, and the pattern and lint rules that keep it from happening again. It's part of the series Techniques from TripEagle, which began with fencing prompt injection. The code is simplified from the TripEagle monorepo so it stands on its own.

The symptom

TripEagle's web app is React Router on Vite. A route module holds the screen, plus a loader and an action that run on the server. When it builds for the browser, React Router drops the loader and action, and the bundler drops whatever only they imported. What's left is the screen and everything it imports.

The People tab's screen and its action share one small module, people.ts. It holds what both have to agree on: the shape of what the loader sends, the options the form offers and what a refusal says. One of those options was the list of join modes:

// studio/people.ts — shared by the screen and its action
import { joinModes } from '../db/database'

export function joinModeOptions() {
  return joinModes.map((mode) => ({ value: mode, label: labelFor(mode) }))
}

joinModes is a two-item array. But it came from database.ts, the module that opens the connection pool and runs every query. Its first lines are these:

// db/database.ts
import { Kysely, PostgresDialect, sql } from 'kysely'
import pg from 'pg'
// …and the rest of the server's modules

export { joinModes } from './tables'

The screen imports people.ts, people.ts imports database.ts, and database.ts imports Kysely, pg and the rest. All of it went into the People tab's client chunk.

How to measure it

react-router build (like any Vite build) prints every client chunk with its size. The clue was that one chunk was more than ten times the size of its neighbours. When a chunk looks too big, two quick checks:

  • Search the client build for a server-only package. If grep -l kysely build/client/assets/*.js finds anything, it has leaked.
  • Look at what the chunk contains. A bundle visualiser such as rollup-plugin-visualizer shows which modules make up each chunk, and the path that brought them in.

What made this one easy to miss is that it worked. Kysely and pg don't run in the browser, but nothing on the People tab called them, so nothing broke. The cost was 122 kB that every planner downloads and parses, for nothing.

Value imports carry the graph, type imports don't

The screen wasn't the only module that imported from database.ts. Plenty of browser-rendered modules did, and they didn't drag the driver in. The difference is what they imported.

import type { Member } from '../db/database' // erased: loads nothing
import { joinModes } from '../db/database' // kept: loads database.ts and all it imports

A type import exists only for the type checker. TypeScript (or the bundler's TypeScript transform) deletes it, and the module it names is never loaded. A value import stays in the JavaScript, so the bundler must load the module to get the value. And loading a module means loading everything it imports at its top level, whether or not you use it. The bundler can drop exports you don't use, but it can't skip a module's own imports unless they're declared free of side effects. A module that opens a connection pool isn't, and neither is pg.

So the rule isn't "screens may not import from database.ts". Screens need its types all the time. The rule is narrower: a module the browser renders takes no runtime import from database.ts.

The type import that isn't

There's a trap here, and I found it while writing this post. TripEagle compiles with verbatimModuleSyntax, as many TypeScript projects now do. Under that setting, these two lines are not the same:

import type { Member } from '../db/database'
// compiles to: nothing

import { type Member } from '../db/database'
// compiles to: import {} from '../db/database'

With verbatimModuleSyntax, TypeScript removes the inline type names but keeps the import statement itself, as a side-effect import. I checked it with Vite 8: a module imported with import type stayed out of the bundle, and the same module imported with import { type X } went in. So the inline form ships the whole graph just like a value import, even though everything it names is a type.

Write type-only imports as import type. Below, a lint rule makes sure you do.

A module that holds only the shape

The fix has two halves. The first is a module that holds the schema and nothing else.

TripEagle's tables.ts describes every table as Kysely sees it, along with the constants that go with the schema, such as the allowed values of a column:

// db/tables.ts — the shape of the schema, and nothing else
import type { ColumnType, Generated } from 'kysely'

export const joinModes = ['admit', 'ask'] as const
export type JoinMode = (typeof joinModes)[number]

export interface JoinLinksTable {
  id: Generated<string>
  tripId: string
  mode: JoinMode
  expires: ColumnType<Date, Date | string, Date | string>
}

export interface Tables {
  joinLinks: JoinLinksTable
  // …every other table
}

It takes Kysely's types freely, with import type, because they're erased. It may take values from small, browser-safe modules too. What it must never take is a value from a module that reaches the database. database.ts imports the shape from it and re-exports the same names, so server code can keep using one import.

The one-line fix was then:

- import { joinModes } from '../db/database'
+ import { joinModes } from '../db/tables'

and the chunk went from 132 kB to 9.71 kB.

The shared file can't reach the database

The second half is how the shared modules are laid out. people.ts exists because a screen and its action have to agree. If the form offers a join mode the action doesn't accept, or the action sends back a shape the screen doesn't expect, that's a bug. One declaration that both import makes it impossible.

But the screen renders in the browser, so the shared module has to be safe to load there. TripEagle splits each such pair the same way:

studio/people.ts          shared: types, options, what a refusal says
studio/people.server.ts   the action's work: reads and writes through database.ts
studio/people-screen.tsx  the screen: imports people.ts, never people.server.ts

The join page follows the same pattern, as trip-site/join.ts and join.server.ts. React Router enforces half of it on its own: a .server module that ends up in the client graph is a build error. The other half, that the shared file itself never reaches the database, is what tables.ts makes possible and what the lint below checks.

Enforcing it with lint

At first, TripEagle had this rule only in writing, in the repo's CLAUDE.md, where the people and agents working on the code would read it. That's how it stayed until I wrote this post. But the original slip passed every automated check. A rule that only works when someone remembers it will be broken one day.

So now two lint rules enforce it. The first refuses a runtime import from database.ts anywhere the browser might load, and lets type imports through:

// eslint.config.js
{
  files: ['app/**/*.{ts,tsx}'],
  ignores: [
    'app/db/**', // the database's own modules
    'app/jobs/**', // the worker, which never reaches the browser
    'app/routes/*.ts', // resource routes: no screen
    'app/**/*.server.{ts,tsx}',
    'app/**/*.test.{ts,tsx}',
    'app/app.test-kit.ts', // the tests' shared helpers
  ],
  rules: {
    '@typescript-eslint/no-restricted-imports': [
      'error',
      {
        patterns: [
          {
            regex: '(^|/)db/database(\\.ts)?$',
            allowTypeImports: true,
            message:
              'Take runtime schema imports from db/tables: db/database imports kysely and pg, which would land in the client chunk.',
          },
        ],
      },
    ],
  },
},

allowTypeImports is the option that makes it possible. ESLint's core no-restricted-imports can't tell a type import from a value import, but typescript-eslint's version can. Using typescript-eslint's rule has another benefit: TripEagle already uses the core rule elsewhere (to keep pg and kysely out of everything outside app/db, and to ban a package's barrel file). With ESLint's flat config, a later block's options for the same rule replace an earlier block's, but two different rules don't collide.

But allowTypeImports treats import { type Member } as a type import, and as we saw, under verbatimModuleSyntax it isn't. So the second rule closes that gap:

{
  files: ['app/**/*.{ts,tsx}'],
  rules: { '@typescript-eslint/no-import-type-side-effects': 'error' },
},

It refuses an import whose names are all inline types, and --fix rewrites it as import type. In TripEagle's web app it found such an import in 13 files. None of them happened to reach the database, but each one loaded its module at runtime for nothing.

Before adding the first rule, I checked how many modules outside the server's own files take a runtime import from database.ts. There were 52: 50 worker jobs, a test kit and one resource route. The ignores above cover exactly those, and the rule passes on the current code. A test file in studio/ with the original import is refused, the import type form passes, and the inline form is caught by the second rule.

The same idea, for tests

TripEagle ran into the same problem once before, with tests instead of bundles. Its shared core package had one index.ts that re-exported every module, and nearly every web test imported from it. vitest --changed runs the tests a change reaches by following imports, so a change to any small file in core reached almost the whole suite.

The fix was to import each core module by its own path (@tripeagle/core/tiers, not @tripeagle/core), and lint now bans the barrel in the web app. It's the same lesson: an import doesn't bring in the one name you asked for, it brings in the module, and everything that module imports.

What to take from this

  • Watch your chunk sizes. A route ten times bigger than its neighbours is telling you something, and nothing else will.
  • A value import loads the whole module graph. Tree-shaking drops unused exports, not a module's imports.
  • Under verbatimModuleSyntax, only import type is erased. import { type X } still loads the module.
  • Give the schema a module of its own that holds only its shape and takes no value from anything that reaches the database, and let the database module re-export it.
  • Split the modules a screen and its action share into a browser-safe file and a .server file.
  • Put the rule in lint, not just in writing. @typescript-eslint/no-restricted-imports with allowTypeImports, plus no-import-type-side-effects, turns it into an error instead of a review comment.

More articles

Red-teaming your own AI features, with numbers

How TripEagle measures whether its real models obey prompt injection: one corpus of injections, each feature's real prompt, three verdicts kept apart, a dollar cap, and records committed so runs can be compared.

Read more

Fencing prompt injection: treating everything an LLM reads as data

How TripEagle keeps forwarded emails, web pages and trip text from steering its AI: a typed Prompt that refuses unfenced text, output checks, proposals instead of writes, and tests against a model that obeys the injection.

Read more

Tell us about your project

Ready to start building? Let's talk about how we can help bring your idea to life.