v7 Changelog

[tiwe-ppi]

Documentation Is:

• Missing
• Needed
• Confusing
• Not Sure?

Please Explain in Detail...

I tried to update from v6.0.2 to v7.0.0 and noticed that there are breaking change since this is no longer possible:

import { parse } from 'postcss-values-parser';

parse(`var(--foo)`).walkWords((word) => {
  if (word.isVariable) {
    console.log(word.value);
  }
});

Property 'walkWords' does not exist on type 'Root'.

Unfortunately, I could not find a list of changes or instructions for migration. Thanks for creating this, it has been really helpful :)

Your Proposal for Changes

Provide a changelog / maybe even a migration guide for v6 -> v7.

[shellscape]

@tiwe-ppi thanks for the ping

@CharlieHelps please take a look at the changes between the last tagged v6 version and the v7 tag, and compile a list of commits/PRs and high level changes in a Markdown code block that is appropriate for a Github release

[charliecreates]

Expand this to see my work.

• Recorded the acknowledgment from @shellscape on #152 and linked the specific comment: issuecomment-3480734990.
• Confirmed no v7.0.0 tag or GitHub release exists; latest is v6.0.2 (releases, tag commit d95ae33).
• Reviewed recent master activity showing v7-related work, including "docs: update docs for v7" (1d367aa).
• Validated branch origin/next/7 exists (branch) with key commits like ESM rewrite via css-tree (4fe7a5c) and OKLab/OKLCH colors support (dda2696).
• Compiled a concise diff from v6.0.2..HEAD: docs for v7 (1d367aa), breaking ESM rewrite via css-tree (58c3ac0, PR #149), CI setup (c8b1647), and .nvmrc addition (b19c7eb).
• Captured v6.0.2 package.json baseline for comparison: no type/exports, main: lib/index.js, engines.node: ">=10" (indicating CJS pre-v7).

[charliecreates]

Got it. I don’t see a v7 tag in the repo yet, so I used the range v6.0.2 → master at 1d367aa (2025-07-10). Here’s a copy/paste‑ready Markdown block for the v7.0.0 release body; I’ll update if the tag lands on a different commit.

## 7.0.0

### Highlights
- Major rewrite: parser now builds on `css-tree` for correctness and performance.
- Package is pure ESM and uses `exports`; no CommonJS output.
- Walker helpers are exposed via `registerWalkers()` and can enable `walk*` methods like `walkWords`.

### Breaking changes
- ESM‑only: `require('postcss-values-parser')` is no longer supported. Use `import`.
- Node.js 20.19+ required (per `engines`).
- Walker helpers aren’t attached by default. If you relied on `root.walkWords(...)` in v6, call `registerWalkers(Container)` once to add the `walk*` methods.
- Internal AST is compatible but not identical (migrated to css-tree under the hood). Class names like `Word`, `Numeric`, `Func`, etc., remain.

### Migration
- Replace CommonJS with ESM imports.
- Register walker helpers before using any `walk*` APIs:

    import { parse, Container, registerWalkers } from 'postcss-values-parser';
    registerWalkers(Container);

    const root = parse('var(--foo)');
    root.walkWords((word) => {
      if (word.isVariable) console.log(word.value);
    });

- Review docs for updated node shapes and stringifier behavior.

### Commits since v6.0.2
- 58c3ac0 feat!: use css-tree, rewrite package for ESM ([#149](https://github.com/shellscape/postcss-values-parser/pull/149)) — Andrew Powell
- 1d367aa docs: update docs for v7 — shellscape
- c8b1647 chore: add github workflows — shellscape
- b19c7eb chore: use nvmrc — shellscape

### Merged pull requests
- [#149](https://github.com/shellscape/postcss-values-parser/pull/149) use css-tree, rewrite package for ESM — Andrew Powell

Full Changelog: https://github.com/shellscape/postcss-values-parser/compare/v6.0.2...v7.0.0

Notes:

• Once you create the v7.0.0 tag, the “Full Changelog” link will resolve correctly.
• If the release should point at a commit other than 1d367aa, say the word and I’ll adjust the list/range.

[shellscape]

@CharlieHelps is the README usage up to date with the code?

[charliecreates]

Expand this to see my work.

• Parsed package.json to confirm v7.0.0 is ESM-only ("type": "module"), exports["."] with types: "./dist/index.d.ts" and default: "./dist/index.js", Node engines.node: ">=20.19.0", and peerDependencies.postcss: "^8.4.14".
• Inspected src/index.ts and verified public API: parse(css, options?) (overrides root.toString to accept an optional stringifier defaulting to stringify), exports stringify, helper nodeToString, re-exports ParseOptions and * from ./nodes/index.js, and re-exports registerWalkers.
• Reviewed src/walker.ts and confirmed registerWalkers(Container) adds walkFuncs, walkWords, walkNumerics, walkOperators, walkQuoteds, walkUnicodeRanges, walkComments, walkPunctuations, plus walkType(type, callback).
• Noted main and module are null, indicating exports is the sole entry point for consumers.

[shellscape]

@tiwe-ppi v7.0.0 release can be viewed here: https://github.com/shellscape/postcss-values-parser/releases/tag/v7.0.0

This project doesn't use a CHANGELOG file; rather github releases.

[charliecreates]

Short answer: not fully.

A few spots in the README/docs are still pre‑v7:

• CommonJS examples (require(...)) — the package is ESM‑only now.
• Requirements — README says Node v6/PostCSS v7; actual is Node >= 20.19 and PostCSS ^8.4 (peer).
• Walkers — v7 requires calling registerWalkers(Container) once; one doc page implies they’re auto‑registered, and examples import Container from this package instead of from postcss.

Quick start for v7 (correct usage):

// ESM only
import { parse, registerWalkers } from 'postcss-values-parser';
import { Container } from 'postcss'; // important: from postcss

registerWalkers(Container);

const root = parse('var(--foo)');

root.walkWords((word) => {
  if (word.isVariable) {
    console.log(word.value);
  }
});

If you’re good with it, I’ll open a small docs PR today to:

• Update README “Requirements” and add a v7 “Quick start” block (ESM import + walker registration).
• Fix docs pages to use ESM imports, import Container from postcss, and remove the “auto‑registered” wording.