feat(astro-purgecss): add includeDefaultContent option

[juanrgm]

Closes #1001

[changeset-bot]

🦋 Changeset detected

Latest commit: e09e4b0

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
astro-purgecss	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[mhdcodes]

hey @juanrgm thanks for creating this PR, I will take a look into this asap.

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/codiume/orbit/astro-purgecss@1045

npm i https://pkg.pr.new/codiume/orbit/astro-seo-meta@1045

npm i https://pkg.pr.new/codiume/orbit/astro-useragent@1045

commit: e09e4b0

[lite-sky]

This looks like it would solve #1001 (although I haven't tried it out) since for that usecase you could set includeDefaultContent: false plus specify specific files or globs in options.content.

Perhaps missing here still is documentation on how to use includeDefaultContent and specify files/globs in the options.content array which include {outDir} in their path.

[mhdcodes]

Yes @lite-sky , this PR was created to address #1001, but I’m still not fully satisfied with the proposed API. I’ll take a bit more time to refine it and make sure we deliver the best solution without breaking any existing functionality.

[mhdcodes]

I'm thinking of an API like this:

export type PurgeCSSOptions = {
  content?: Array<string | RawContent> | (() => Array<string | RawContent>);
};

This would allow users to pass a function that returns custom paths. If a function is provided, it will take precedence and everything else will be ignored.

[juanrgm]

That was my first option, but it's confusing.

There are only four options.

1. Update the main version and remove the default content value.
2. Add an option to disable the default behavior (this PR request).
3. Add a function option to customize the options before passing them to purgecss.
4. Add support for negative patterns.

The cleanest option is the number 2.

[mhdcodes]

That was my first option, but it's confusing.

There are only four options.

1. Update the main version and remove the default content value.
2. Add an option to disable the default behavior (this PR request).
3. Add a function option to customize the options before passing them to purgecss.
4. Add support for negative patterns.

The cleanest option is the number 2.

1. is a breaking change.
2. is a good option but I'm still 50% / 50%
3. is actually good, something like excludeContent ?

[lite-sky]

For my usecase with a very large number of pages, an excludeContent or negative pattern makes things very complicated when I only want to include 10-20 individual pages. So for me, some way of including would be preferred.

I like the includeDefaultContent: boolean option, and maybe then combined with the function option like this?

export type PurgeCSSOptions = {
  content?: Array<string | RawContent> | ((outDir: string) => Array<string | RawContent>);
};

The content Array or function would both provide additions to the default content (unless it was excluded using includeDefaultContent: false). The outDir: string parameter to the function gives users explicit access to the configured outDir, rather than relying on a pattern in the path.

Another potential for the function option would be as a separate field in PurgeCSSOptions like this:

export type PurgeCSSOptions = {
  content?: Array<string | RawContent>;
  contentFunc?: ((outDir: string) => Array<string | RawContent>);
};

The user could specify either, both or none of content and contentFunc. Each would add to the array passed to Purgecss. Combined with includeDefaultContent, the user has full control over what gets passed to Purgecss.

[mhdcodes]

closed in-favor of #1288, thank you all for the valuable feedback 🙏 . this has been sitting stale for a long time it's good to have it resolved.