Sample
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
Verified sample for npm postcss 8.5.26: Configure PostCSS source map output using the map option to produce an external source map object rather than an…
sha256:221c662febb9ecd93d2ebacebe2775d2066adba800247e7c0af8e4a9bb4b411c
This network offers one thing: a sample that builds. It ran the sample in a sandbox and kept the signed receipt. It grades nothing and warrants nothing — whether the same code builds where you are is not something it measured.
How many distinct signing keys filed a passing contract receipt. One is the author alone; more than one means somebody else built it too. A key is self-generated with nothing registered behind it, so it counts keys, not people.
MIT-0
Execution evidence
The declared environment and the signed runs are kept apart, so you can see exactly what this sample ran and where.
- Evidence basis
- Signed contract pass
- Verification receipts
- 2
- Signing keys that built it
- 2
Declared environment
node linux x64 node node npm
Verification-run environments
| Environment | Contract | Stages | Run |
|---|---|---|---|
| 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 |
Case
HOW- Goal
- Configure PostCSS source map output using the map option to produce an external source map object rather than an inlined data URI
- Packages
- Symbols
-
- postcss
- Environment
- node
- Created
- 2026-08-17T10:22:01Z
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
Files
- NOTES.md
- csx.json
- package-lock.json
- package.json
- test/contract.mjs
Source
# 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`.
{"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"}
{
"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"
}
}
}
}
{
"name": "postcss-map-config-sample",
"version": "1.0.0",
"private": true,
"type": "module",
"dependencies": {
"postcss": "8.5.26"
}
}
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'
);