Socket
Socket
Sign inDemoInstall

postcss-import

Package Overview
Dependencies
17
Maintainers
2
Versions
54
Alerts
File Explorer

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

postcss-import

PostCSS plugin to import CSS files


Version published
Maintainers
2
Weekly downloads
11,235,568
increased by3.26%
Bundle size
10 kB
Minified + gzipped

Weekly downloads

Package description

What is postcss-import?

The postcss-import npm package is a plugin for PostCSS that allows you to import local files, node modules, or web_modules into your CSS files. It can be used to modularize your CSS and help manage large stylesheets by splitting them into smaller, more maintainable pieces.

What are postcss-import's main functionalities?

Importing local files

Allows you to import a local CSS file into another CSS file. This is useful for splitting your CSS into smaller, more manageable files.

@import 'local-file.css';

Importing node modules

Enables you to import CSS from a node module installed in your project's node_modules directory. This is useful for including third-party stylesheets in your project.

@import 'npm-module-name';

Importing from web_modules

Allows you to import CSS from web_modules, which can be useful if you are using a package manager that supports this feature, like Snowpack.

@import 'web-module-name';

Customizing import paths

Lets you customize the paths where postcss-import looks for CSS files to import. This is helpful when you have a specific directory structure and want to keep your imports clean and relative to those paths.

postcss([ require('postcss-import')({ path: ['src/css', 'src/styles'] }) ]);

Other packages similar to postcss-import

Readme

Source

postcss-import

Build Version postcss compatibility

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 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...). Tests are made from the path & the content of imported files (using a hash table). 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 to extend postcss-import.
  • If you want to import remote sources, you can use 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).

Installation

$ 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.

// 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:

/* 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:

@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 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

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 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, similar files (based on the same content) are being skipped. It's to optimize output and skip similar files like normalize.css for example. If this behavior is not what you want, just set this option to false to disable it.

addModulesDirectories

Type: Array
Default: []

An array of folder names to add to Node's resolver. 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
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

License

Keywords

FAQs

Last updated on 20 Mar 2024

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc