PostCSS Parcel Import Fix

0.0.2 · abandoned · verified Wed Apr 22

postcss-parcel-import is a PostCSS plugin, currently at version 0.0.2, designed as a temporary workaround for a specific `@import` bug (issue #1165) encountered in older versions of `parcel-bundler`. The plugin introduces a custom `@parcel-import` at-rule, which Parcel v1 users could leverage to ensure CSS `@import` rules were correctly processed before other PostCSS transformations. This package has seen no updates since 2018, coinciding with the closure of the Parcel issue it addressed and the deprecation of `parcel-bundler` (Parcel v1) in favor of Parcel v2. It differentiates itself by providing a very specific, now obsolete, syntax extension to handle a bug that has long since been resolved in the Parcel ecosystem. Its release cadence was minimal, comprising a single version.

Common errors

```
Error: Cannot find module 'postcss-parcel-import'
```
cause The package is not installed or the path is incorrect.

fix `npm install postcss-parcel-import` or `yarn add postcss-parcel-import`
```
Undefined variable $red
```
cause This error often occurs when PostCSS plugins that rely on imported variables (like `postcss-simple-vars`) run *before* an import plugin (like `postcss-parcel-import` or `postcss-import`) has inlined the CSS containing those variable definitions. This was precisely the core problem `postcss-parcel-import` aimed to address in Parcel v1.

fix Ensure that your PostCSS plugin order correctly places import-handling plugins (like `postcss-import`) at the beginning of the plugin chain, *before* any plugins that consume imported CSS features such as variables or mixins. For Parcel v2, rely on its native `@import` resolution or `postcss-import` in your `.postcssrc` file.

Warnings

deprecated This package is a temporary solution for a bug in `parcel-bundler` (Parcel v1), which has been deprecated. The bug (parcel-bundler/parcel#1165) was closed in 2018. This plugin is no longer necessary for current versions of Parcel.
Fix: Migrate to Parcel v2 (`parcel` package) where the original bug is resolved. Do not use `postcss-parcel-import` with modern Parcel versions. For standard CSS `@import` handling, Parcel's built-in capabilities or `postcss-import` are typically sufficient.
breaking The custom `@parcel-import` syntax introduced by this plugin is non-standard CSS. If this plugin is removed without updating affected stylesheets, any `@parcel-import` rules will result in invalid CSS.
Fix: Replace all instances of `@parcel-import` with standard `@import` rules, and ensure your build setup correctly handles CSS imports (e.g., using `postcss-import` if needed, or relying on Parcel's native import resolution).
gotcha The plugin is archived and read-only on GitHub since March 2, 2022, and has not received updates since 2018. It is not compatible with modern PostCSS or Parcel ecosystems.
Fix: Avoid using this package in new projects. For existing projects, prioritize migration away from Parcel v1 and this plugin.

Install

npm install postcss-parcel-import npm
yarn add postcss-parcel-import yarn
pnpm add postcss-parcel-import pnpm

Imports

postcssParcelImport
wrong:
```
import { postcssParcelImport } from 'postcss-parcel-import';
```
correct:
```
import postcssParcelImport from 'postcss-parcel-import';
```
While primarily used via `require()`, modern bundlers can handle default ESM import for CommonJS modules. No named exports exist.
require
```
const postcssParcelImport = require('postcss-parcel-import');
```
This is the primary and most commonly shown way to use PostCSS plugins in CommonJS environments, as demonstrated in the package's README.

Quickstart

Demonstrates how to load and apply the `postcss-parcel-import` plugin using the PostCSS API.

const postcss = require('postcss');
const postcssParcelImport = require('postcss-parcel-import');

const cssInput = `
  @parcel-import '../mixins.pcss';
  .container {
    color: var(--primary-color);
  }
`;

async function processCss() {
  try {
    const result = await postcss([postcssParcelImport()]).process(cssInput, { from: 'src/app.css' });
    console.log('Processed CSS:\n', result.css);
    console.log('Warnings:\n', result.warnings().toString());
  } catch (error) {
    console.error('PostCSS processing error:', error);
  }
}

processCss();

/* 
Note: For this plugin to actually 'fix' an @import issue, 
      it needs to be run within the context of an affected 
      Parcel v1 build process. Running it standalone with 
      PostCSS will process the custom @parcel-import rule 
      but won't perform actual file inlining without further 
      custom PostCSS resolver logic or integration into Parcel.
      The example above merely demonstrates plugin invocation.
*/

view raw JSON →