# postcss-import

> PostCSS plugin to import CSS files

Latest version **17.0.0** (published 2026-08-14) · MIT license · 0 weekly downloads

## Install

```sh
npm install postcss-import
pnpm add postcss-import
yarn add postcss-import
bun add postcss-import
```

## Health

**Score 63/100 (C)** — status: active.

Positive: has types package; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 17.0.0 |
| Published | 2026-08-14 |
| First published | 2014-08-10 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/postcss-import) |
| Module format | CommonJS |
| Node | >=22.0.0 |
| Dependencies | 3 |
| Unpacked size | 29.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1410 |
| Author | Maxime Thirouin |
| Maintainers | ai, ryanzim, romainmenke |
| Keywords | css, postcss, postcss-plugin, import, node modules, npm |

## Links

- npm: https://www.npmjs.com/package/postcss-import
- Repository: https://github.com/postcss/postcss-import
- Homepage: https://github.com/postcss/postcss-import#readme
- Issues: https://github.com/postcss/postcss-import/issues
- npm.io page: https://npm.io/package/postcss-import

## Dependencies (3)

- [resolve](https://npm.io/package/resolve.md) ^1.1.7
- [read-cache](https://npm.io/package/read-cache.md) ^1.0.0
- [postcss-value-parser](https://npm.io/package/postcss-value-parser.md) ^4.0.0

## Alternatives

- [style-dictionary](https://npm.io/package/style-dictionary.md) — 2.0M weekly downloads
- [postcss-merge-idents](https://npm.io/package/postcss-merge-idents.md) — 1.7M weekly downloads
- [@fontsource/noto-sans](https://npm.io/package/@fontsource/noto-sans.md) — 93.0K weekly downloads
- [uglifycss](https://npm.io/package/uglifycss.md) — 71.6K weekly downloads
- [mat4-interpolate](https://npm.io/package/mat4-interpolate.md) — 23.3K weekly downloads

## Recent versions

- 17.0.0 (latest) — 2026-08-14
- 16.2.0 — 2026-08-12
- 16.1.1 — 2025-06-17
- 16.1.0 — 2024-03-20
- 16.0.1 — 2024-02-15
- 16.0.0 — 2024-01-03
- 15.1.0 — 2022-12-07
- 15.0.1 — 2022-12-01
- 15.0.0 — 2022-08-30
- 14.1.0 — 2022-03-22
- 14.0.2 — 2021-05-10
- 14.0.1 — 2021-03-31
- 14.0.0 — 2020-12-14
- 13.0.0 — 2020-10-20
- 12.0.1 — 2018-10-23
- … 42 more at https://npm.io/package/postcss-import/versions

## README

# postcss-import

[![Version](https://img.shields.io/npm/v/postcss-import)](https://github.com/postcss/postcss-import/blob/master/CHANGELOG.md)
[![postcss compatibility](https://img.shields.io/npm/dependency-version/postcss-import/peer/postcss)](https://postcss.org/)

> [PostCSS](https://github.com/postcss/postcss) plugin to transform `@import`
rules by inlining content.

This plugin can consume local files, node modules or web_modules.
To resolve path of an `@import` rule, it can look into root directory
(by default `process.cwd()`), `web_modules`, `node_modules`
or local modules.
_When importing a module, it will look for `index.css` or file referenced in
`package.json` in the `style` or `main` fields._
You can also provide manually multiples paths where to look at.

**Notes:**

- **This plugin should probably be used as the first plugin of your list.
This way, other plugins will work on the AST as if there were only a single file
to process, and will probably work as you can expect**.
- Running [postcss-url](https://github.com/postcss/postcss-url) after
postcss-import in your plugin chain will allow you to adjust assets `url()` (or
even inline them) after inlining imported files.
- In order to optimize output, **this plugin will only import a file once** on
a given scope (root, media query...).
Duplicates are detected by the resolved file path.
If this behavior is not what you want, look at `skipDuplicates` option
- If you are looking for **Glob Imports**, you can use [postcss-import-ext-glob](https://github.com/dimitrinicolas/postcss-import-ext-glob) to extend postcss-import.
- If you want to import remote sources, you can use [postcss-import-url](https://github.com/unlight/postcss-import-url) with its `dataUrls` plugin option to extend postcss-import.
- Imports which are not modified (by `options.filter` or because they are remote
  imports) are moved to the top of the output.
- **This plugin attempts to follow the CSS `@import` spec**; `@import`
  statements must precede all other statements (besides `@charset` and `@layer`).

## Installation

```console
$ npm install -D postcss-import
```

## Usage

Unless your stylesheet is in the same place where you run postcss
(`process.cwd()`), you will need to use `from` option to make relative imports
work.

```js
// dependencies
const fs = require("fs")
const postcss = require("postcss")
const atImport = require("postcss-import")

// css to be processed
const css = fs.readFileSync("css/input.css", "utf8")

// process css
postcss()
  .use(atImport())
  .process(css, {
    // `from` option is needed here
    from: "css/input.css"
  })
  .then((result) => {
    const output = result.css

    console.log(output)
  })
```

`css/input.css`:

```css
/* remote urls are preserved */
@import "https://example.com/styles.css";

/* can consume `node_modules`, `web_modules` or local modules */
@import "cssrecipes-defaults"; /* == @import "../node_modules/cssrecipes-defaults/index.css"; */
@import "normalize.css"; /* == @import "../node_modules/normalize.css/normalize.css"; */

@import "foo.css"; /* relative to css/ according to `from` option above */

/* all standard notations of the "url" value are supported */
@import url(foo-1.css);
@import url("foo-2.css");

@import "bar.css" (min-width: 25em);

@import 'baz.css' layer(baz-layer);

body {
  background: black;
}
```

will give you:

```css
@import "https://example.com/styles.css";

/* ... content of ../node_modules/cssrecipes-defaults/index.css */
/* ... content of ../node_modules/normalize.css/normalize.css */

/* ... content of css/foo.css */

/* ... content of css/foo-1.css */
/* ... content of css/foo-2.css */

@media (min-width: 25em) {
/* ... content of css/bar.css */
}

@layer baz-layer {
/* ... content of css/baz.css */
}

body {
  background: black;
}
```

Checkout the [tests](test) for more examples.

### Options

#### `filter`
Type: `Function`  
Default: `() => true`

Only transform imports for which the test function returns `true`. Imports for
which the test function returns `false` will be left as is. The function gets
the path to import as an argument and should return a boolean.

#### `root`

Type: `String`  
Default: `process.cwd()` or _dirname of
[the postcss `from`](https://github.com/postcss/postcss#node-source)_

Define the root where to resolve path (eg: place where `node_modules` are).
Should not be used that much.  
_Note: nested `@import` will additionally benefit of the relative dirname of
imported files._

#### `path`

Type: `String|Array`  
Default: `[]`

A string or an array of paths in where to look for files.

#### `plugins`

Type: `Array`  
Default: `undefined`

An array of plugins to be applied on each imported files.

#### `resolve`

Type: `Function`  
Default: `null`

You can provide a custom path resolver with this option. This function gets
`(id, basedir, importOptions, astNode)` arguments and should return a path, an array of
paths or a promise resolving to the path(s). If you do not return an absolute
path, your path will be resolved to an absolute path using the default
resolver.
You can use [resolve](https://github.com/substack/node-resolve) for this.

#### `load`

Type: `Function`  
Default: null

You can overwrite the default loading way by setting this option.
This function gets `(filename, importOptions)` arguments and returns content or
promised content.

#### `skipDuplicates`

Type: `Boolean`  
Default: `true`

By default, repeated imports of the same file are skipped.
Set this option to `false` to inline a file each time it is imported.

#### `addModulesDirectories`

Type: `Array`  
Default: `[]`

An array of folder names to add to [Node's resolver](https://github.com/substack/node-resolve).
Values will be appended to the default resolve directories:
`["node_modules", "web_modules"]`.

This option is only for adding additional directories to default resolver. If
you provide your own resolver via the `resolve` configuration option above, then
this value will be ignored.

#### `warnOnEmpty`

Type: `Boolean`  
Default: `true`

By default `postcss-import` warns when an empty file is imported.  
Set this option to `false` to disable this warning.

#### Example with some options

```js
const postcss = require("postcss")
const atImport = require("postcss-import")

postcss()
  .use(atImport({
    path: ["src/css"],
  }))
  .process(cssString)
  .then((result) => {
    const { css } = result
  })
```

## `dependency` Message Support

`postcss-import` adds a message to `result.messages` for each `@import`. Messages are in the following format:

```
{
  type: 'dependency',
  file: absoluteFilePath,
  parent: fileContainingTheImport
}
```

This is mainly for use by postcss runners that implement file watching.

---

## CONTRIBUTING

* ⇄ Pull requests and ★ Stars are always welcome.
* For bugs and feature requests, please create an issue.
* Pull requests must be accompanied by passing automated tests (`$ npm test`).

## [Changelog](CHANGELOG.md)

## [License](LICENSE)

---
_Source: https://npm.io/package/postcss-import · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._