performance/namespace-import · Namespace import

Prefer named imports over import * as for tree-shaking.

Severity: info · Category: performance

What it checks

Flags a value import * as X from '<package>' from a bare (node_modules) package when X is used as a whole somewhere in the file: indexed by a variable (X[key]), passed on (fn(X)), spread, or enumerated (Object.keys(X)). A namespace read only through static member access (X.foo(), X['foo'], {X.foo} or <X.Component /> in markup) tree-shakes like named imports and is not flagged. A local of the same name that shadows X (a function parameter, an {#each} item or index, a snippet parameter, an {@const}, a let: directive) is not a use of the namespace. Type-only imports (import type * as T) and non-bare specifiers (relative, $lib, $app, $env, #…, and the @/… and ~/… alias prefixes, which no package name can take) are not flagged.

Why it matters

A namespace import (import * as X) is only tree-shakeable while every access to X stays static (X.foo()). Passing X around, or indexing it dynamically (X[key]), forces the bundler to assume every export is reachable and keep the whole module.

Named imports are reliably shakeable and make the dependency surface explicit. With a bundler that tree-shakes, that can cut real weight from packages like three or d3; the guarantee is the shakeability, not a smaller bundle in every setup.

How to fix

<script>
  // Instead of:  import * as _ from 'lodash';
  import debounce from 'lodash/debounce';

  // Instead of:  import * as THREE from 'three';
  import { Scene, WebGLRenderer } from 'three';
</script>

Mode differences

None. This rule reads source, the same .svelte and .ts files, everywhere it runs. The CLI, the Vite plugin’s build pass, and the live dashboard’s static baseline all report it identically, and the rendered-HTML pass never re-evaluates it. Scoping a run with --route skips it: component-scoped rules have no route to attribute a finding to.

Disabling

Silence a single occurrence with  on the line above it, or turn the rule off:

export default {
  rules: {
    'performance/namespace-import': 'off'
  }
};