Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Surface documentation for @parcel/transformer-css errorRecovery flag #1071

Open
bnjmnrsh opened this issue Jan 19, 2023 · 1 comment
Open

Comments

@bnjmnrsh
Copy link

I've found it quite difficult to find information about implementing the "@parcel/transformer-css": errorRecovery flag, and was trying various combinations of adding it to .parcelrc or as a flag on the watch or build commands without success.

The only approach that seems to work is to add it to package.json which I gleaned after many hours of search from a comment in a closed issue:

 "@parcel/transformer-css": {
    "errorRecovery": true
  }, 

I also surmised that the flag could only be passed to the css-cli as this appears to be the only real documentation, but it doesn't mention package.json at all. Further, search in the documentation doesn't currently return any results for errorRecovery or --error-recovery, nor is there any mention in the sass or css sections of the documentation.

Quick digression, I personally really try to avoid adding configuration to package.json as it is easily overlooked and hard to remember its there. This is the reason that I spent so long trying to invoke the correct magical gestures that would get the setting to work from within .parcelrc instead -- if such a thing is possible, I'd be happy to know how.

One could say that the documentation on .parcelrc is a bit of misdirection in this regard:

Parcel works out of the box for many projects with zero configuration. But if you want more control, or need to extend or override Parcel’s defaults, you can do so by creating a .parcelrc file in your project.

@bnjmnrsh
Copy link
Author

Thanks to @devongovett 's explanation about the mechanics and reasoning behind @parcel/transformer-css and LightningCSS's errorRecovery option, I can see that the configuration of this particular feature will remain in package.json for the foreseeable future.

So there are a few things in the current CSS docs that I feel could be expanded to make the feature better understood:
First LightingCSS isn't mentioned until the very end in the minification section, which is a shame, one because it's an awesome project in its own right worth highlighting, and two, there a few other small options in addition to errorRecovery that some might be interested in. Given this I'd say it would be useful add the following bits of information, much of which could just signpost to the LightningCSS Parcel docs.

  • Intro: Reference the CSS module is built on LightningCSS
  • New Heading: "Lightning CSS" (after PostCSS before Production?)
    • Brief intro to Lightning CSS, similar to PostCSS intro text
    • Outline the 'default' config provided by Parcel and that custom config can be added to package.json
    • Advisory note about errorRecovery ie "Should your project rely on malformed CSS tricks such as IE hacks then the errorRecovery option can be added to your package.json.
    • Signpost to LightningCSS for additional detials.

Also:

  • Plugins Docs add quick clarification that:
    • .parcelrc is for Parcel's own internal plugin configuration. Parcel honours the configuration of any of its included tools such as PostCSS or TypeScript using their own config files or in package.json. See configuration notes in each language for details.

If the above outline of changes looks okay, and if it would be welcome, I'd be happy to put forward a first draft.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant