CodeSampleX

サンプル

postcss 8.5.26: Configure PostCSS source map output using the map option to produce an external source map object rather than an inlined data URI

検証済みサンプル — npm postcss 8.5.26: Configure PostCSS source map output using the map option to produce an external source map object rather than an inlined data…

sha256:221c662febb9ecd93d2ebacebe2775d2066adba800247e7c0af8e4a9bb4b411c

このネットワークが提供するのは一つだけです。ビルドされるサンプル。サンドボックスで実行し、署名済みの受領証を保管します。等級はつけず、何も保証しません — 同じコードがあなたの環境でビルドされるかは測定していません。 合格した契約受領証を提出した異なる署名鍵の数です。1 なら作者だけ、2 以上なら他の誰かもビルドしています。鍵は自己生成で背後に登録された身元がないため、数えているのは人ではなく鍵です。 MIT-0

実行証拠

宣言された環境と署名済みの実行を分けてあります。このサンプルが何をどこで実行したかをそのまま確認できます。

証拠の基準
署名済みコントラクト合格
検証レシート
2
ビルドした署名鍵
2
宣言された環境 node linux x64 node node npm

検証実行環境

環境 コントラクト ステージ 実行日
node 22 · linux alpine/x64 · docker ed25519:d91480838ac982c9 PASS compile:SKIPPED · contract:PASS · load:PASS · resolve:PASS
CONTAINER_RUN · node-typescript@1
2026-08-17
node 22 · linux alpine/x64 · docker ed25519:2175b912ea1c23b1 PASS compile:SKIPPED · contract:PASS · load:PASS · resolve:PASS
CONTAINER_RUN · node-typescript@1
2026-08-18

ケース

HOW
ゴール
Configure PostCSS source map output using the map option to produce an external source map object rather than an inlined data URI
パッケージ
シンボル
  • postcss
環境
node
作成日
2026-08-17T10:22:01Z

コントラクト

  1. postcss.process(css, { map: true }) leaves result.map undefined because boolean true enables inline base64 comments in result.css, requiring map: { inline: false } to populate result.map with an external SourceMapGenerator
  2. map: { inline: false } populates result.map with a SourceMapGenerator whose toJSON() contains sources and mappings, while appending an external /*# sourceMappingURL=output.css.map */ comment to result.css
  3. map: { annotation: false } or map: { inline: false, annotation: false } populates result.map with an external SourceMapGenerator without appending any sourceMappingURL comment to result.css
  4. map: false disables source mapping entirely and strips existing sourceMappingURL comments from input CSS, leaving result.map undefined
  5. map: { prev: false, inline: false } ignores existing source map comments in input CSS and roots new mappings to the immediate input file rather than chaining previous sources

ファイル

  • NOTES.md
  • csx.json
  • package-lock.json
  • package.json
  • test/contract.mjs

ソースアーティファクトをダウンロード (tar.gz)

ソース

NOTES.md
# PostCSS Source Map Configuration Behavior

## Known Solutions Search

A search via `search_known_solution` for `postcss` yielded existing samples covering `@tailwindcss/postcss` plugin interactions:
- `sha256:7844de612517f8f5156daa2f0a6282d39d3510ccb3784110a987ff5a430d5353`: Load legacy JavaScript configuration and plugins in `@tailwindcss/postcss` using CSS `@config`.
- `sha256:9e575485d0464963ebc669172d2536435d7c106e4ff7e03c0c1e880920213d09`: Configure `@tailwindcss/postcss` with options and prove legacy config requires CSS `@config`.
- `sha256:aa188b7b67f5779bf01bd31aa78e2e8b8c8d8d7fa6e1b2965f19a11d9b156062`: Rebuild `@tailwindcss/postcss` output when in-memory input CSS changes.

This contract tests the core `postcss` package `map` option configuration.

## Pinned Version

- `postcss`: `8.5.26`

## Observed Behavior and Failure Mode

### The `map: true` vs `map: { inline: false }` Trap

When processing CSS with PostCSS, passing `map: true` enables inline source maps by default (`inline: true`). Under inline mapping:
- `result.map` is `undefined`.
- The source map is serialized as a base64 Data URI inside a trailing comment in `result.css`: `/*# sourceMappingURL=data:application/json;base64,... */`.

### Failure Mode

Build scripts attempting to write external `.css` and `.css.map` files often assume `map: true` populates `result.map`:
```javascript
const result = await postcss(plugins).process(inputCss, {
  from: 'src/components/button.css',
  to: 'dist/components/button.css',
  map: true
});
fs.writeFileSync('dist/components/button.css', result.css);
fs.writeFileSync('dist/components/button.css.map', result.map.toString());
```
This fails loudly at runtime with:
```
TypeError: Cannot read properties of undefined (reading 'toString')
```

### Verified Configuration Rules

1. **External Source Map Generator**: Passing `map: { inline: false }` leaves `result.css` containing a relative URL comment (`/*# sourceMappingURL=button.css.map */`) and populates `result.map` with an instance of `SourceMapGenerator`.
2. **Omit Source Map Comment**: Passing `map: { annotation: false }` or `map: { inline: false, annotation: false }` generates `result.map` but produces `result.css` with no trailing comment.
3. **Strip Existing Source Maps**: Passing `map: false` strips any existing `/*# sourceMappingURL=... */` comments present in the input CSS and leaves `result.map` as `undefined`.
4. **Disconnect Source Map History**: Passing `map: { prev: false, inline: false }` disables automatic chaining of upstream source map comments from prior build tools, establishing the current input file as the root source in `result.map.toJSON().sources`.
csx.json
{"case":{"believed":"Passing map: true to postcss.process() returns a separate source map generator object on result.map","caseId":"case:sha256:9914db0dc351200c4ed7f28ee5be84ef2fd87698f81321f786162d2e2a0d9879","contract":["postcss.process(css, { map: true }) leaves result.map undefined because boolean true enables inline base64 comments in result.css, requiring map: { inline: false } to populate result.map with an external SourceMapGenerator","map: { inline: false } populates result.map with a SourceMapGenerator whose toJSON() contains sources and mappings, while appending an external /*# sourceMappingURL=output.css.map */ comment to result.css","map: { annotation: false } or map: { inline: false, annotation: false } populates result.map with an external SourceMapGenerator without appending any sourceMappingURL comment to result.css","map: false disables source mapping entirely and strips existing sourceMappingURL comments from input CSS, leaving result.map undefined","map: { prev: false, inline: false } ignores existing source map comments in input CSS and roots new mappings to the immediate input file rather than chaining previous sources"],"goal":"Configure PostCSS source map output using the map option to produce an external source map object rather than an inlined data URI","kind":"HOW","packages":["pkg:npm/postcss@8.5.26"],"schemaVersion":1,"symbols":["postcss"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","ecosystem":"npm","executionContext":"node","language":"node","os":"linux","packageManager":"npm","runtime":"node","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/postcss@8.5.26"],"schemaVersion":1,"symbols":["postcss"],"verifierAdapter":"node-typescript@1"}
package-lock.json
{
  "name": "postcss-map-config-sample",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "postcss-map-config-sample",
      "version": "1.0.0",
      "dependencies": {
        "postcss": "8.5.26"
      }
    },
    "node_modules/nanoid": {
      "version": "3.3.18",
      "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.18.tgz",
      "integrity": "sha512-DTg4MJbGMWkfi6VZFdNt2/caMbQy4Ou+Op/hJQvGEWcnVfoA1QA+xzRKAzw9jD6+GVOOeYr/mIcuDSdug6F6+w==",
      "funding": [
        {
          "type": "github",
          "url": "https://github.com/sponsors/ai"
        }
      ],
      "license": "MIT",
      "bin": {
        "nanoid": "bin/nanoid.cjs"
      },
      "engines": {
        "node": "^10 || ^12 || ^13.7 || ^14 || >=15.0.1"
      }
    },
    "node_modules/picocolors": {
      "version": "1.1.1",
      "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz",
      "integrity": "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==",
      "license": "ISC"
    },
    "node_modules/postcss": {
      "version": "8.5.26",
      "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.26.tgz",
      "integrity": "sha512-u82N74LFzG8ca+dD8puPnplTXoGH4fTPpVGuIbt36G3qvNlkvfD0lEAZSxaly3KX8TS/L1A1gsCEmvKmBcVbkQ==",
      "funding": [
        {
          "type": "opencollective",
          "url": "https://opencollective.com/postcss/"
        },
        {
          "type": "tidelift",
          "url": "https://tidelift.com/funding/github/npm/postcss"
        },
        {
          "type": "github",
          "url": "https://github.com/sponsors/ai"
        }
      ],
      "license": "MIT",
      "dependencies": {
        "nanoid": "^3.3.17",
        "picocolors": "^1.1.1",
        "source-map-js": "^1.2.1"
      },
      "engines": {
        "node": "^10 || ^12 || >=14"
      }
    },
    "node_modules/source-map-js": {
      "version": "1.2.1",
      "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.1.tgz",
      "integrity": "sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==",
      "license": "BSD-3-Clause",
      "engines": {
        "node": ">=0.10.0"
      }
    }
  }
}
package.json
{
  "name": "postcss-map-config-sample",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "dependencies": {
    "postcss": "8.5.26"
  }
}
test/contract.mjs
import assert from 'node:assert';
import postcss from 'postcss';

const sampleCss = '.button { display: inline-flex; color: blue; }';

// 1. Passing map: true produces an inline source map in result.css and leaves result.map undefined
const inlineResult = postcss().process(sampleCss, {
  from: 'src/components/button.css',
  to: 'dist/components/button.css',
  map: true
});
assert.strictEqual(
  inlineResult.map,
  undefined,
  'result.map should be undefined when map: true is configured'
);
assert.ok(
  inlineResult.css.includes('/*# sourceMappingURL=data:application/json;base64,'),
  'result.css should contain an inlined base64 data URI comment'
);

// 2. Passing map: { inline: false } generates an external SourceMapGenerator on result.map and appends a file comment
const externalResult = postcss().process(sampleCss, {
  from: 'src/components/button.css',
  to: 'dist/components/button.css',
  map: { inline: false }
});
assert.strictEqual(
  typeof externalResult.map,
  'object',
  'result.map must be an object when map: { inline: false } is configured'
);
assert.strictEqual(
  typeof externalResult.map.toString,
  'function',
  'result.map must provide a toString() serializer'
);
const externalMapData = externalResult.map.toJSON();
assert.strictEqual(externalMapData.version, 3);
assert.deepStrictEqual(externalMapData.sources, ['../../src/components/button.css']);
assert.strictEqual(externalMapData.file, 'button.css');
assert.ok(
  externalResult.css.includes('/*# sourceMappingURL=button.css.map */'),
  'result.css should end with an external sourceMappingURL comment'
);
assert.ok(
  !externalResult.css.includes('data:application/json;base64,'),
  'result.css should not contain an inline base64 map when inline is false'
);

// 3. Passing map: { annotation: false } generates result.map without appending any comment to result.css
const noAnnotationResult = postcss().process(sampleCss, {
  from: 'src/components/button.css',
  to: 'dist/components/button.css',
  map: { annotation: false }
});
assert.strictEqual(
  typeof noAnnotationResult.map,
  'object',
  'result.map must still be generated when annotation is false'
);
assert.ok(
  !noAnnotationResult.css.includes('sourceMappingURL'),
  'result.css must not contain any sourceMappingURL comment when annotation is false'
);

// 4. Passing map: false disables source mapping entirely and strips any previous sourceMappingURL comments
const cssWithInlineMap = inlineResult.css;
const disabledResult = postcss().process(cssWithInlineMap, {
  from: 'dist/components/button.css',
  to: 'dist/components/button.min.css',
  map: false
});
assert.strictEqual(
  disabledResult.map,
  undefined,
  'result.map must be undefined when map: false'
);
assert.ok(
  !disabledResult.css.includes('sourceMappingURL'),
  'map: false must strip prior sourceMappingURL annotations from output CSS'
);

// 5. Passing map: { prev: false, inline: false } disconnects source mapping history
const chainedResult = postcss().process(cssWithInlineMap, {
  from: 'dist/components/button.css',
  to: 'dist/components/button.min.css',
  map: { inline: false }
});
assert.deepStrictEqual(
  chainedResult.map.toJSON().sources,
  ['../../src/components/button.css'],
  'Chained processing should trace back to the original source file by default'
);

const unchainedResult = postcss().process(cssWithInlineMap, {
  from: 'dist/components/button.css',
  to: 'dist/components/button.min.css',
  map: { prev: false, inline: false }
});
assert.deepStrictEqual(
  unchainedResult.map.toJSON().sources,
  ['button.css'],
  'prev: false should ignore the input map and root source mapping to the current input file'
);

オリジンシーダー

csx-seed