NextjsAbsolute Imports & Module Aliases

Absolute Imports & Module Aliases

As a component tree grows deeper, relative imports like ../../../../components/Button become fragile and hard to read — move a file one level, and every import path pointing to it breaks. Next.js has built-in support for TypeScript's baseUrl and paths settings, letting you write short, absolute import paths instead, resolved from your project root.
baseUrl and paths in tsconfig.json
baseUrl defines the root that non-relative imports are resolved from. paths goes a step further, letting you define custom aliases that map to specific folders — the two are often used together.

tsconfig.json

JSON
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./*"],
      "@components/*": ["./src/components/*"],
      "@utils/*": ["./src/utils/*"]
    }
  }
}
Note
Next.js ships a default @/* alias out of the box in new projects (created via create-next-app), pointing at the project root — so @/components/Button typically works immediately, even before adding any custom aliases of your own.
Before and after

Before — relative imports

TSX
import Button from '../../../../components/common/Button'
import { formatDate } from '../../../utils/date'
import { AppConfig } from '../../../../config'

After — absolute imports via aliases

TSX
import Button from '@components/common/Button'
import { formatDate } from '@utils/date'
import { AppConfig } from '@config'

The second version reads the same regardless of how deeply nested the importing file is, and moving a file no longer requires touching every import that points to it — only the alias mapping (if it changes at all) needs updating.

Custom aliases, one per concern

tsconfig.json — a richer set of aliases

JSON
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["./*"],
      "@components/*": ["./src/components/*"],
      "@hooks": ["./src/hooks"],
      "@utils/*": ["./src/utils/*"],
      "@config": ["./src/config"]
    }
  }
}

Pattern

Resolves to

Use for

@/*

Project root

General catch-all alias

@components/*

src/components/*

UI components

@utils/*

src/utils/*

Helper/utility functions

@config

src/config

App-wide configuration singletons

No further Next.js configuration is needed — as soon as baseUrl/paths are set in tsconfig.json, Next.js's compiler and webpack resolver both understand the new paths automatically, and editors like VS Code pick them up for autocomplete and "go to definition" too.

  • Absolute imports are configured entirely in tsconfig.json — no next.config.js changes required.

  • baseUrl sets the root for non-relative imports; paths defines named aliases on top of it.

  • New Next.js projects get a default @/* alias pointing at the project root.

  • Aliases make imports resistant to files moving and easier to scan at a glance.