Skip to content

Commit

Permalink
Improve multi-root @config linking (#15001)
Browse files Browse the repository at this point in the history 
This PR improves the discoverability of Tailwind config files when we
are trying to link them to your CSS files.

When you have multiple "root" CSS files in your project, and if they
don't include an `@config` directive, then we tried to find the Tailwind
config file in your current working directory.

This means that if you run the upgrade command from the root of your
project, and you have a nested folder with a separate Tailwind setup,
then the nested CSS file would link to the root Tailwind config file.

Visually, you can think of it like this:

```
.
├── admin
│   ├── src
│   │   └── styles
│   │       └── index.css       <-- This will be linked to (1)
│   └── tailwind.config.js      (2)
├── src
│   └── styles
│       └── index.css           <-- This will be linked to (1)
└── tailwind.config.js          (1)
```

If you run the upgrade command from the root of your project, then the
`/src/styles/index.css` will be linked to `/tailwind.config.js` which is
what we expect.

But `/admin/src/styles/index.css` will _also_ be linked to
`/tailwind.config.js`

With this PR we improve this behavior by looking at the CSS file, and
crawling up the parent tree. This mens that the new behavior looks like
this:

```
.
├── admin
│   ├── src
│   │   └── styles
│   │       └── index.css       <-- This will be linked to (2)
│   └── tailwind.config.js      (2)
├── src
│   └── styles
│       └── index.css           <-- This will be linked to (1)
└── tailwind.config.js          (1)
```

Now `/src/styles/index.css` will be linked to `/tailwind.config.js`, and
`/admin/src/styles/index.css` will be linked to
`/admin/tailwind.config.js`.

When we discover the Tailwind config file, we will also print a message
to the user to let them know which CSS file is linked to which Tailwind
config file.

This should be a safe improvement because if your Tailwind config file
had a different name, or if it lived in a sibling folder then Tailwind
wouldn't find it either and you already required a `@config "…";`
directive in your CSS file to point to the correct file.

In the unlikely event that it turns out that 2 (or more) CSS files
resolve to the same to the same Tailwind config file, then an upgrade
might not be safe and some manual intervention might be needed. In this
case, we will show a warning about this.

<img width="1552" alt="image"
src="https://github.com/user-attachments/assets/7a1ad11d-18c5-4b7d-9a02-14f0116ae955">


Test plan:
---

- Added an integration test that properly links the nearest Tailwind
config file by looking up the tree
- Added an integration test that resolves 2 or more CSS files to the
same config file, resulting in an error where manual intervention is
needed
- Ran it on the Tailwind UI codebase

Running this on Tailwind UI's codebase it looks like this:

<img width="1552" alt="image"
src="https://github.com/user-attachments/assets/21785428-5e0d-47f7-80ec-dab497f58784">

---------

Co-authored-by: Jordan Pittman <jordan@cryptica.me>
  • Loading branch information
@RobinMalfait @thecrypticace
RobinMalfait and thecrypticace authored Nov 18, 2024
1 parent dd3441b commit 08c6c96
Show file tree
Hide file tree
Showing 9 changed files with 287 additions and 104 deletions.
1 change: 1 addition & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

- Ensure `flex` is suggested ([#15014](https://github.com/tailwindlabs/tailwindcss/pull/15014))
- _Upgrade (experimental)_: Resolve imports when specifying a CSS entry point on the command-line ([#15010](https://github.com/tailwindlabs/tailwindcss/pull/15010))
- _Upgrade (experimental)_: Resolve nearest Tailwind config file when CSS file does not contain `@config` ([#15001](https://github.com/tailwindlabs/tailwindcss/pull/15001))

### Changed

Expand Down
186 changes: 145 additions & 41 deletions integrations/upgrade/index.test.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1385,9 +1385,7 @@ test(
export default {
content: ['./src/**/*.{html,js}'],
plugins: [
() => {
// custom stuff which is too complicated to migrate to CSS
},
() => {}, // custom stuff which is too complicated to migrate to CSS
],
}
`,
Expand All @@ -1396,20 +1394,28 @@ test(
class="!flex sm:!block bg-gradient-to-t bg-[--my-red]"
></div>
`,
'src/root.1.css': css`
'src/root.1/index.css': css`
/* Inject missing @config */
@tailwind base;
@tailwind components;
@tailwind utilities;
`,
'src/root.2.css': css`
'src/root.1/tailwind.config.ts': js`
export default {
content: ['./src/**/*.{html,js}'],
plugins: [
() => {}, // custom stuff which is too complicated to migrate to CSS
],
}
`,
'src/root.2/index.css': css`
/* Already contains @config */
@tailwind base;
@tailwind components;
@tailwind utilities;
@config "../tailwind.config.ts";
@config "../../tailwind.config.ts";
`,
'src/root.3.css': css`
'src/root.3/index.css': css`
/* Inject missing @config above first @theme */
@tailwind base;
@tailwind components;
Expand All @@ -1425,18 +1431,35 @@ test(
--color-blue-500: #00f;
}
`,
'src/root.4.css': css`
'src/root.3/tailwind.config.ts': js`
export default {
content: ['./src/**/*.{html,js}'],
plugins: [
() => {}, // custom stuff which is too complicated to migrate to CSS
],
}
`,
'src/root.4/index.css': css`
/* Inject missing @config due to nested imports with tailwind imports */
@import './root.4/base.css';
@import './root.4/utilities.css';
@import './base.css';
@import './utilities.css';
`,
'src/root.4/tailwind.config.ts': js`
export default {
content: ['./src/**/*.{html,js}'],
plugins: [
() => {}, // custom stuff which is too complicated to migrate to CSS
],
}
`,
'src/root.4/base.css': css`@import 'tailwindcss/base';`,
'src/root.4/utilities.css': css`@import 'tailwindcss/utilities';`,

'src/root.5.css': css`@import './root.5/tailwind.css';`,
'src/root.5/index.css': css`@import './tailwind.css';`,
'src/root.5/tailwind.css': css`
/* Inject missing @config in this file, due to full import */
@import 'tailwindcss/tailwind.css';
/* Should be located in the root: ../../ */
@import 'tailwindcss';
`,
},
},
Expand All @@ -1450,11 +1473,11 @@ test(
class="flex! sm:block! bg-linear-to-t bg-(--my-red)"
></div>
--- ./src/root.1.css ---
--- ./src/root.1/index.css ---
/* Inject missing @config */
@import 'tailwindcss';
@config '../tailwind.config.ts';
@config './tailwind.config.ts';
/*
The default border color has changed to \`currentColor\` in Tailwind CSS v4,
Expand All @@ -1474,11 +1497,11 @@ test(
}
}
--- ./src/root.2.css ---
--- ./src/root.2/index.css ---
/* Already contains @config */
@import 'tailwindcss';
@config "../tailwind.config.ts";
@config "../../tailwind.config.ts";
/*
The default border color has changed to \`currentColor\` in Tailwind CSS v4,
Expand All @@ -1498,11 +1521,11 @@ test(
}
}
--- ./src/root.3.css ---
--- ./src/root.3/index.css ---
/* Inject missing @config above first @theme */
@import 'tailwindcss';
@config '../tailwind.config.ts';
@config './tailwind.config.ts';
@variant hocus (&:hover, &:focus);
Expand Down Expand Up @@ -1532,15 +1555,12 @@ test(
}
}
--- ./src/root.4.css ---
--- ./src/root.4/index.css ---
/* Inject missing @config due to nested imports with tailwind imports */
@import './root.4/base.css';
@import './root.4/utilities.css';
@config '../tailwind.config.ts';
@import './base.css';
@import './utilities.css';
--- ./src/root.5.css ---
@import './root.5/tailwind.css';
@config './tailwind.config.ts';
--- ./src/root.4/base.css ---
@import 'tailwindcss/theme' layer(theme);
Expand All @@ -1567,8 +1587,12 @@ test(
--- ./src/root.4/utilities.css ---
@import 'tailwindcss/utilities' layer(utilities);
--- ./src/root.5/index.css ---
@import './tailwind.css';
--- ./src/root.5/tailwind.css ---
/* Inject missing @config in this file, due to full import */
/* Should be located in the root: ../../ */
@import 'tailwindcss';
@config '../../tailwind.config.ts';
Expand All @@ -1595,13 +1619,92 @@ test(
},
)

test(
'multiple CSS roots that resolve to the same Tailwind config file requires manual intervention',
{
fs: {
'package.json': json`
{
"dependencies": {
"tailwindcss": "^3",
"@tailwindcss/upgrade": "workspace:^"
}
}
`,
'tailwind.config.ts': js`
export default {
content: ['./src/**/*.{html,js}'],
plugins: [
() => {}, // custom stuff which is too complicated to migrate to CSS
],
}
`,
'src/index.html': html`
<div
class="!flex sm:!block bg-gradient-to-t bg-[--my-red]"
></div>
`,
'src/root.1.css': css`
/* Inject missing @config */
@tailwind base;
@tailwind components;
@tailwind utilities;
`,
'src/root.2.css': css`
/* Already contains @config */
@tailwind base;
@tailwind components;
@tailwind utilities;
@config "../tailwind.config.ts";
`,
'src/root.3.css': css`
/* Inject missing @config above first @theme */
@tailwind base;
@tailwind components;
@tailwind utilities;
@variant hocus (&:hover, &:focus);
@theme {
--color-red-500: #f00;
}
@theme {
--color-blue-500: #00f;
}
`,
'src/root.4.css': css`
/* Inject missing @config due to nested imports with tailwind imports */
@import './root.4/base.css';
@import './root.4/utilities.css';
`,
'src/root.4/base.css': css`@import 'tailwindcss/base';`,
'src/root.4/utilities.css': css`@import 'tailwindcss/utilities';`,

'src/root.5.css': css`@import './root.5/tailwind.css';`,
'src/root.5/tailwind.css': css`
/* Inject missing @config in this file, due to full import */
@import 'tailwindcss/tailwind.css';
`,
},
},
async ({ exec }) => {
let output = await exec('npx @tailwindcss/upgrade --force', {}, { ignoreStdErr: true }).catch(
(e) => e.toString(),
)

expect(output).toMatch('Could not determine configuration file for:')
},
)

test(
'injecting `@config` in the shared root, when a tailwind.config.{js,ts,…} is detected',
{
fs: {
'package.json': json`
{
"dependencies": {
"tailwindcss": "^3",
"@tailwindcss/upgrade": "workspace:^"
}
}
Expand Down Expand Up @@ -1662,14 +1765,14 @@ test(

expect(await fs.dumpFiles('./src/**/*.{html,css}')).toMatchInlineSnapshot(`
"
--- ./src/index.css ---
@import './tailwind-setup.css';
--- ./src/index.html ---
<div
class="flex! sm:block! bg-linear-to-t bg-(--my-red)"
></div>
--- ./src/index.css ---
@import './tailwind-setup.css';
--- ./src/base.css ---
@import 'tailwindcss/theme' layer(theme);
@import 'tailwindcss/preflight' layer(base);
Expand Down Expand Up @@ -1735,6 +1838,7 @@ test(
'package.json': json`
{
"dependencies": {
"tailwindcss": "^3",
"@tailwindcss/upgrade": "workspace:^"
}
}
Expand Down Expand Up @@ -1797,14 +1901,14 @@ test(

expect(await fs.dumpFiles('./src/**/*.{html,css}')).toMatchInlineSnapshot(`
"
--- ./src/index.css ---
@import './tailwind-setup.css';
--- ./src/index.html ---
<div
class="flex! sm:block! bg-linear-to-t bg-(--my-red)"
></div>
--- ./src/index.css ---
@import './tailwind-setup.css';
--- ./src/base.css ---
@import 'tailwindcss/theme' layer(theme);
@import 'tailwindcss/preflight' layer(base);
Expand Down Expand Up @@ -2105,13 +2209,6 @@ test(
// Files should not be modified
expect(await fs.dumpFiles('./*.{js,css,html}')).toMatchInlineSnapshot(`
"
--- index.html ---
<div>
<div class="shadow shadow-sm shadow-xs"></div>
<div class="blur blur-xs"></div>
<div class="rounded rounded-sm"></div>
</div>
--- index.css ---
@import 'tailwindcss';
Expand Down Expand Up @@ -2141,6 +2238,13 @@ test(
border-color: var(--color-gray-200, currentColor);
}
}
--- index.html ---
<div>
<div class="shadow shadow-sm shadow-xs"></div>
<div class="blur blur-xs"></div>
<div class="rounded rounded-sm"></div>
</div>
"
`)
},
Expand Down Expand Up @@ -2196,9 +2300,6 @@ test(
// Files should not be modified
expect(await fs.dumpFiles('./*.{js,css,html,tsx}')).toMatchInlineSnapshot(`
"
--- index.html ---
<div class="rounded-sm blur-sm shadow-sm"></div>
--- index.css ---
@import 'tailwindcss';
Expand All @@ -2220,6 +2321,9 @@ test(
}
}
--- index.html ---
<div class="rounded-sm blur-sm shadow-sm"></div>
--- example-component.tsx ---
type Star = [
x: number,
Expand Down
12 changes: 9 additions & 3 deletions integrations/utils.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -346,15 +346,21 @@ export function test(
let zParts = z[0].split('/')
let aFile = aParts.at(-1)
let zFile = aParts.at(-1)
let zFile = zParts.at(-1)
// Sort by depth, shallow first
if (aParts.length < zParts.length) return -1
if (aParts.length > zParts.length) return 1
// Sort by folder names, alphabetically
for (let i = 0; i < aParts.length - 1; i++) {
let diff = aParts[i].localeCompare(zParts[i])
if (diff !== 0) return diff
}
// Sort by filename, sort files named `index` before others
if (aFile?.startsWith('index')) return -1
if (zFile?.startsWith('index')) return 1
if (aFile?.startsWith('index') && !zFile?.startsWith('index')) return -1
if (zFile?.startsWith('index') && !aFile?.startsWith('index')) return 1
// Sort by filename, alphabetically
return a[0].localeCompare(z[0])
Expand Down
Loading

0 comments on commit 08c6c96

Please sign in to comment.