Skip to content

v7 Changelog #152

Closed
Closed
v7 Changelog#152

Description

@tiwe-ppi
tiwe-ppi
opened on Nov 3, 2025

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.

Activity

  1. shellscape commented on Nov 3, 2025

    @shellscape
    shellscape
    on Nov 3, 2025
    Owner

    @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

  2. charliecreates commented on Nov 3, 2025

    @charliecreates
    charliecreatesbot
    on Nov 3, 2025 – with CharlieCreates
    Contributor
    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).

  3. charliecreates commented on Nov 3, 2025

    @charliecreates
    charliecreatesbot
    on Nov 3, 2025 – with CharlieCreates
    Contributor

    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.

  4. shellscape commented on Nov 3, 2025

    @shellscape
    shellscape
    on Nov 3, 2025
    Owner

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

  5. charliecreates commented on Nov 3, 2025

    @charliecreates
    charliecreatesbot
    on Nov 3, 2025 – with CharlieCreates
    Contributor
    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.

  6. shellscape commented on Nov 3, 2025

    @shellscape
    shellscape
    on Nov 3, 2025
    Owner

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

  7. charliecreates commented on Nov 3, 2025

    @charliecreates
    charliecreatesbot
    on Nov 3, 2025 – with CharlieCreates
    Contributor

    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.
  8. ghost closed this as completedon Nov 3, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions