wrapper/tailwindcss
1
0
Fork 0
Code Issues Pull requests Projects Releases 1 Packages Wiki Activity Actions
tailwindcss/packages/@tailwindcss-node/src/index.ts

19 lines
732 B
TypeScript
Raw Normal View History

Support loading config files via `@config` (#14239) In Tailwind v4 the CSS file is the main entry point to your project and is generally configured via `@theme`. However, given that all v3 projects were configured via a `tailwind.config.js` file we definitely need to support those. This PR adds support for loading existing Tailwind config files by adding an `@config` directive to the CSS — similar to how v3 supported multiple config files except that this is now _required_ to use a config file. You can load a config file like so: ``` @import "tailwindcss"; @config "./path/to/tailwind.config.js"; ``` A few notes: - Both CommonJS and ESM config files are supported (loaded directly via `import()` in Node) - This is not yet supported in Intellisense or Prettier — should hopefully land next week - TypeScript is **not yet** supported in the config file — this will be handled in a future PR. --------- Co-authored-by: Philipp Spiess <hello@philippspiess.com> Co-authored-by: Adam Wathan <adam.wathan@gmail.com> Co-authored-by: Robin Malfait <malfait.robin@gmail.com>
2024-09-02 12:03:16 -04:00
import * as Module from 'node:module'
import { pathToFileURL } from 'node:url'
Expose timing information in debug mode (#14553) This PR exposes when using the the `DEBUG` environment variable. This follows the `DEBUG` conventions where: - `DEBUG=1` - `DEBUG=true` - `DEBUG=*` - `DEBUG=tailwindcss` Will enable the debug information, but when using: - `DEBUG=0` - `DEBUG=false` - `DEBUG=-tailwindcss` It will not. This currently only exposes some timings related to: 1. Scanning for candidates 2. Building the CSS 3. Optimizing the CSS We can implement a more advanced version of this where we also expose more fine grained information such as the files we scanned, the amount of candidates we found and so on. But I believe that this will be enough to start triaging performance related issues.
2024-09-30 16:39:21 +02:00
import * as env from './env'
Template migrations: Migrate v3 prefixes to v4 (#14557) This PR adds a new migration that can migrate Tailwind CSS v3 style prefixes into Tailwind CSS v4. The migration is split into three separate pieces of work: 1. Firstly, we need to read the full JavaScript config to get the _old_ prefix option. This is necessary because in v4, we will not allow things like custom-separators for the prefix. From this option we will then try and compute a new prefix (in 90% of the cases this is going to just remove the trailing `-` but it can also work in more complex cases). 2. Then we migrate all Candidates. The important thing here is that we need to operate on the raw candidate string because by relying on `parseCandidate` (which we do for all other migrations) would not work, as the candidates are not valid in v4 syntax. More on that in a bit. 3. Lastly we also make sure to update the CSS config to include the new prefix. This is done by prepending the prefix option like so: ```css @import "tailwindcss" prefix(tw); ``` ### Migrating candidates The main difference between v3 prefixes and v4 prefixes is that in v3, the prefix was _part of the utility_ where as in v4 it is _always in front of the CSS class. So, for example, this candidate in v3: ``` hover:-tw-mr-4 ``` Would be converted to the following in v4: ``` tw:hover:-mr-4 ``` Since the first example _won't parse as a valid Candidate in v4, as the `tw-mr` utility does not exist, we have to operate on the raw candidate string first. To do this I created a fork of the `parseCandidate` function _without any validation of utilities or variants_. This is used to identify part of the candidate that is the `base` and then ensuring the `base` starts with the old prefix. We then remove this to create an "unprefixed" candidate that we validate against a version of the DesignSystem _with no prefixes configured_. If the variant is valid this way, we can then print it again with the `DesignSystem` that has the new prefix to get the migrated version. Since we set up the `DesignSystem` to include the new prefix, we can also be certain that migrations that happen afterwards would still disqualify candidates that aren't valid according to the new prefix policy. This does mean we need to have the prefix fixup be the first step in our pipeline. One interesting bit is that in v3, arbitrary properties did not require prefixes where as in v4 they do. So the following candidate: ``` [color:red] ``` Will be converted to: ``` tw:[color:red] ```
2024-10-01 18:04:08 +02:00
export { __unstable__loadDesignSystem, compile } from './compile'
Resolve `@import` in core (#14446) This PR brings `@import` resolution into Tailwind CSS core. This means that our clients (PostCSS, Vite, and CLI) no longer need to depend on `postcss` and `postcss-import` to resolve `@import`. Furthermore this simplifies the handling of relative paths for `@source`, `@plugin`, or `@config` in transitive CSS files (where the relative root should always be relative to the CSS file that contains the directive). This PR also fixes a plugin resolution bug where non-relative imports (e.g. directly importing node modules like `@plugin '@tailwindcss/typography';`) would not work in CSS files that are based in a different npm package. ### Resolving `@import` The core of the `@import` resolution is inside `packages/tailwindcss/src/at-import.ts`. There, to keep things performant, we do a two-step process to resolve imports. Imagine the following input CSS file: ```css @import "tailwindcss/theme.css"; @import "tailwindcss/utilities.css"; ``` Since our AST walks are synchronous, we will do a first traversal where we start a loading request for each `@import` directive. Once all loads are started, we will await the promise and do a second walk where we actually replace the AST nodes with their resolved stylesheets. All of this is recursive, so that `@import`-ed files can again `@import` other files. The core `@import` resolver also includes extensive test cases for [various combinations of media query and supports conditionals as well als layered imports](https://developer.mozilla.org/en-US/docs/Web/CSS/@import). When the same file is imported multiple times, the AST nodes are duplicated but duplicate I/O is avoided on a per-file basis, so this will only load one file, but include the `@theme` rules twice: ```css @import "tailwindcss/theme.css"; @import "tailwindcss/theme.css"; ``` ### Adding a new `context` node to the AST One limitation we had when working with the `postcss-import` plugin was the need to do an additional traversal to rewrite relative `@source`, `@plugin`, and `@config` directives. This was needed because we want these paths to be relative to the CSS file that defines the directive but when flattening a CSS file, this information is no longer part of the stringifed CSS representation. We worked around this by rewriting the content of these directives to be relative to the input CSS file, which resulted in added complexity and caused a lot of issues with Windows paths in the beginning. Now that we are doing the `@import` resolution in core, we can use a different data structure to persist this information. This PR adds a new `context` node so that we can store arbitrary context like this inside the Ast directly. This allows us to share information with the sub tree _while doing the Ast walk_. Here's an example of how the new `context` node can be used to share information with subtrees: ```ts const ast = [ rule('.foo', [decl('color', 'red')]), context({ value: 'a' }, [ rule('.bar', [ decl('color', 'blue'), context({ value: 'b' }, [ rule('.baz', [decl('color', 'green')]), ]), ]), ]), ] walk(ast, (node, { context }) => { if (node.kind !== 'declaration') return switch (node.value) { case 'red': assert(context.value === undefined) case 'blue': assert(context.value === 'a') case 'green': assert(context.value === 'b') } }) ``` In core, we use this new Ast node specifically to persist the `base` path of the current CSS file. We put the input CSS file `base` at the root of the Ast and then overwrite the `base` on every `@import` substitution. ### Removing the dependency on `postcss-import` Now that we support `@import` resolution in core, our clients no longer need a dependency on `postcss-import`. Furthermore, most dependencies also don't need to know about `postcss` at all anymore (except the PostCSS client, of course!). This also means that our workaround for rewriting `@source`, the `postcss-fix-relative-paths` plugin, can now go away as a shared dependency between all of our clients. Note that we still have it for the PostCSS plugin only, where it's possible that users already have `postcss-import` running _before_ the `@tailwindcss/postcss` plugin. Here's an example of the changes to the dependencies for our Vite client ✨ : <img width="854" alt="Screenshot 2024-09-19 at 16 59 45" src="https://github.com/user-attachments/assets/ae1f9d5f-d93a-4de9-9244-61af3aff1237"> ### Performance Since our Vite and CLI clients now no longer need to use `postcss` at all, we have also measured a significant improvement to the initial build times. For a small test setup that contains only a hand full of files (nothing super-complex), we measured an improvement in the **3.5x** range: <img width="1334" alt="Screenshot 2024-09-19 at 14 52 49" src="https://github.com/user-attachments/assets/06071fb0-7f2a-4de6-8ec8-f202d2cc78e5"> The code for this is in the commit history if you want to reproduce the results. The test was based on the Vite client. ### Caveats One thing to note is that we previously relied on finding specific symbols in the input CSS to _bail out of Tailwind processing completely_. E.g. if a file does not contain a `@tailwind` or `@apply` directive, it can never be a Tailwind file. Since we no longer have a string representation of the flattened CSS file, we can no longer do this check. However, the current implementation was already inconsistent with differences on the allowed symbol list between our clients. Ideally, Tailwind CSS should figure out wether a CSS file is a Tailwind CSS file. This, however, is left as an improvement for a future API since it goes hand-in-hand with our planned API changes for the core `tailwindcss` package. --------- Co-authored-by: Jordan Pittman <jordan@cryptica.me>
2024-09-23 17:05:55 +02:00
export * from './normalize-path'
Expose timing information in debug mode (#14553) This PR exposes when using the the `DEBUG` environment variable. This follows the `DEBUG` conventions where: - `DEBUG=1` - `DEBUG=true` - `DEBUG=*` - `DEBUG=tailwindcss` Will enable the debug information, but when using: - `DEBUG=0` - `DEBUG=false` - `DEBUG=-tailwindcss` It will not. This currently only exposes some timings related to: 1. Scanning for candidates 2. Building the CSS 3. Optimizing the CSS We can implement a more advanced version of this where we also expose more fine grained information such as the files we scanned, the amount of candidates we found and so on. But I believe that this will be enough to start triaging performance related issues.
2024-09-30 16:39:21 +02:00
export { env }
Support loading config files via `@config` (#14239) In Tailwind v4 the CSS file is the main entry point to your project and is generally configured via `@theme`. However, given that all v3 projects were configured via a `tailwind.config.js` file we definitely need to support those. This PR adds support for loading existing Tailwind config files by adding an `@config` directive to the CSS — similar to how v3 supported multiple config files except that this is now _required_ to use a config file. You can load a config file like so: ``` @import "tailwindcss"; @config "./path/to/tailwind.config.js"; ``` A few notes: - Both CommonJS and ESM config files are supported (loaded directly via `import()` in Node) - This is not yet supported in Intellisense or Prettier — should hopefully land next week - TypeScript is **not yet** supported in the config file — this will be handled in a future PR. --------- Co-authored-by: Philipp Spiess <hello@philippspiess.com> Co-authored-by: Adam Wathan <adam.wathan@gmail.com> Co-authored-by: Robin Malfait <malfait.robin@gmail.com>
2024-09-02 12:03:16 -04:00
// In Bun, ESM modules will also populate `require.cache`, so the module hook is
// not necessary.
if (!process.versions.bun) {
let localRequire = Module.createRequire(import.meta.url)
Fix a crash with older Node.js versions (#14342) Closes #14341 --------- Co-authored-by: Jordan Pittman <jordan@cryptica.me>
2024-09-04 19:43:18 +02:00
// `Module#register` was added in Node v18.19.0 and v20.6.0
//
// Not calling it means that while ESM dependencies don't get reloaded, the
// actual included files will because they cache bust directly via `?id=…`
Module.register?.(pathToFileURL(localRequire.resolve('@tailwindcss/node/esm-cache-loader')))
Support loading config files via `@config` (#14239) In Tailwind v4 the CSS file is the main entry point to your project and is generally configured via `@theme`. However, given that all v3 projects were configured via a `tailwind.config.js` file we definitely need to support those. This PR adds support for loading existing Tailwind config files by adding an `@config` directive to the CSS — similar to how v3 supported multiple config files except that this is now _required_ to use a config file. You can load a config file like so: ``` @import "tailwindcss"; @config "./path/to/tailwind.config.js"; ``` A few notes: - Both CommonJS and ESM config files are supported (loaded directly via `import()` in Node) - This is not yet supported in Intellisense or Prettier — should hopefully land next week - TypeScript is **not yet** supported in the config file — this will be handled in a future PR. --------- Co-authored-by: Philipp Spiess <hello@philippspiess.com> Co-authored-by: Adam Wathan <adam.wathan@gmail.com> Co-authored-by: Robin Malfait <malfait.robin@gmail.com>
2024-09-02 12:03:16 -04:00
}
Reference in a new issue Copy permalink