miel.truyen/nx
1
0
Fork 0
Code Issues Pull Requests Actions 6 Packages Projects Releases Wiki Activity

docs(angular): simplify tailwind css recipes for angular projects (#17684)

Browse Source
This commit is contained in:
Leosvel Pérez Espinosa 2023-06-20 15:02:34 +01:00 committed by GitHub
parent 99739179c7
commit 2503249901
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 43 additions and 157 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

200
docs/shared/guides/using-tailwind-css-with-angular-projects.md
View File

@ -1,6 +1,6 @@
# Using Tailwind CSS with Angular projects # Using Tailwind CSS with Angular projects
The purpose of this guide is to cover how to use and configure [Tailwind CSS](https://tailwindcss.com/) The purpose of this page is to cover how to use and configure [Tailwind CSS](https://tailwindcss.com/)
with [Angular](https://angular.io/) projects. It shows the different options available to set it up in existing projects with [Angular](https://angular.io/) projects. It shows the different options available to set it up in existing projects
or new projects, and it also contains a set of our recommended setups for using Tailwind CSS in different scenarios that or new projects, and it also contains a set of our recommended setups for using Tailwind CSS in different scenarios that
can be found on an Nx workspace. can be found on an Nx workspace.
@ -8,71 +8,47 @@ can be found on an Nx workspace.
For an in-depth look on this topic, be sure to check out our blog For an in-depth look on this topic, be sure to check out our blog
post [Set up Tailwind CSS with Angular in an Nx workspace](https://medium.com/nrwl/set-up-tailwind-css-with-angular-in-an-nx-workspace-6f039a0f4479). post [Set up Tailwind CSS with Angular in an Nx workspace](https://medium.com/nrwl/set-up-tailwind-css-with-angular-in-an-nx-workspace-6f039a0f4479).
## Get Started ## Generating or adding Tailwind CSS support to Angular projects
To generate an Angular application or library with Tailwind CSS configured, add the `--add-tailwind` flag to the generate command: To generate an Angular application with Tailwind CSS configured run:
```shell ```shell
npx nx g @nx/angular:app my-app --add-tailwind npx nx g @nx/angular:app my-app --add-tailwind
``` ```
To generate an Angular buildable library with Tailwind CSS configured run:
```shell ```shell
npx nx g @nx/angular:lib my-lib --buildable --add-tailwind npx nx g @nx/angular:lib my-lib --buildable --add-tailwind
``` ```
To add Tailwind to an existing project, run the [setup-tailwind](/packages/angular/generators/setup-tailwind) generator: To generate an Angular publishable library with Tailwind CSS configured run:
```shell
npx nx g @nx/angular:lib my-lib --publishable --importPath=@my-org/my-lib --add-tailwind
```
To add Tailwind CSS to an existing Angular application, buildable library or publishable library, run:
```shell ```shell
npx nx g @nx/angular:setup-tailwind my-project npx nx g @nx/angular:setup-tailwind my-project
``` ```
## Tailwind CSS support by the Nx Angular plugin You can see the available options for the above generator in [its docs](/packages/angular/generators/setup-tailwind).
The Nx Angular plugin provides support for Tailwind CSS v2 and v3. The support includes the following features: ## Configuring the content sources for a project and its dependencies
- A generator called `@nx/angular:setup-tailwind` that configures Tailwind CSS in an existing project. Tailwind CSS scans files looking for class names to generate only the CSS needed by what's being used in those files.
- An option `--add-tailwind` for the `@nx/angular:app` generator to create an application with Tailwind CSS To configure which files should be processed, the `tailwind.config.js` has a `content` property (formerly called `purge`
pre-configured. in v2). You can find more details on Tailwind's
- An option `--add-tailwind` for the `@nx/angular:lib` generator to create a library with Tailwind CSS pre-configured. [official documentation](https://tailwindcss.com/docs/content-configuration#configuring-source-paths).
This option can only be used with buildable and publishable libraries.
- Ability to build buildable libraries with Tailwind CSS using the `@nx/angular:ng-packagr-lite` executor.
- Ability to build publishable libraries with Tailwind CSS using the `@nx/angular:package` executor.
The generation for existing or new projects will perform the following steps: The `content` property usually consists of a glob pattern to include all the necessary files that should be processed.
- Check if the `tailwindcss` package is already installed and if not installed, it will install the necessary
packages (`tailwindcss`, `postcss` and `autoprefixer`)
- Create a `tailwind.config.js` file in the project root with the default configuration to get started (specific to the
installed version) and set up to scan the content (or purge for v2) of the project's source and its dependencies (
using the [`createGlobPatternsForDependencies` utility function](#createglobpatternsfordependencies-utility-function))
- Based on the project type, it will perform the following actions:
- Applications: update the application styles entry point file located at `apps/app1/src/styles.css` by including
the Tailwind CSS base styles
- Libraries: add the `tailwind.config.js` file path to the `build` target configuration
{% callout type="note" title="More details" %}
When Tailwind CSS has not been installed yet, the generator will install Tailwind CSS v3. Only if Tailwind CSS v2 is
installed, the generator will use it and generate the configuration accordingly.
{% /callout %}
> All the examples in this guide will use Tailwind CSS v3, but the guide will work the same for v2. To convert the
> examples to v2, check
> the [Tailwind CSS upgrade guide](https://tailwindcss.com/docs/upgrade-guide#migrating-to-the-jit-engine) to understand
> the differences between the configuration for both versions.
### `createGlobPatternsForDependencies` utility function
One of the advantages of Tailwind is that it post-processes your CSS removing (also called "purging") all the parts that
are not being used. In order to configure which file should be processed, the `tailwind.config.js` has a `content`
property (formerly called `purge` in v2). You can find more details on
Tailwind's [official documentation](https://tailwindcss.com/docs/content-configuration#configuring-source-paths).
The `content` property usually consistes of a glob pattern to include all the necessary files that should be processed.
In an Nx workspace it is very common for a project to have other projects as its dependencies. Setting and updating the In an Nx workspace it is very common for a project to have other projects as its dependencies. Setting and updating the
glob to reflect those dependencies and their files is cumbersome and error prone. glob to reflect those dependencies and their files is cumbersome and error prone.
Nx has a utility function that can be used to construct the glob representation of all files a project depends on (based Nx has a utility function (`createGlobPatternsForDependencies`) that can be used to construct the glob representation of
on the Nx Project Graph). all files a project depends on (based on the Nx Project Graph).
The function receives a directory path that is used to identify the project for which the dependencies are going to be The function receives a directory path that is used to identify the project for which the dependencies are going to be
identified (therefore it needs to be a directory path within a project). It can also receive an optional glob pattern to identified (therefore it needs to be a directory path within a project). It can also receive an optional glob pattern to
@ -110,7 +86,7 @@ and `lib2` as dependencies, the utility function will return the following glob
``` ```
{% callout type="note" title="Usage with Module Federation" %} {% callout type="note" title="Usage with Module Federation" %}
When using Tailwind with Module Federation, Tailwind starts its purge at the host application, and only includes direct When using Tailwind with Module Federation, Tailwind starts scanning files at the host application, and only includes direct
dependencies of that application. As the other applications in the Module Federation are not direct dependencies, but dependencies of that application. As the other applications in the Module Federation are not direct dependencies, but
rather runtime dependencies, this can lead to missing classes from being included in your generated Tailwind css file. rather runtime dependencies, this can lead to missing classes from being included in your generated Tailwind css file.
@ -125,53 +101,14 @@ This can be fixed in two manners:
{% /callout %} {% /callout %}
## Generating or adding Tailwind CSS support to Angular projects
### Generate an Angular application with Tailwind CSS pre-configured
To generate an Angular application with Tailwind CSS configured by default, you can use the following command:
```shell
npx nx g @nx/angular:app my-app --add-tailwind
```
### Generate an Angular buildable library with Tailwind CSS pre-configured
To generate an Angular buildable library with Tailwind CSS configured by default, you can use the following command:
```shell
npx nx g @nx/angular:lib my-lib --buildable --add-tailwind
```
### Generate an Angular publishable library with Tailwind CSS pre-configured
To generate an Angular publishable library with Tailwind CSS configured by default, you can use the following command:
```shell
npx nx g @nx/angular:lib my-lib --publishable --importPath=@my-org/my-lib --add-tailwind
```
### Add Tailwind CSS to an existing Angular application, buildable library or publishable library
To add Tailwind CSS to an existing Angular application, buildable library or publishable library, you can use the
following command:
```shell
npx nx g @nx/angular:setup-tailwind my-project
```
You can see the available options for the above generator in [its docs](/packages/angular/generators/setup-tailwind).
## Tailwind CSS setup scenarios ## Tailwind CSS setup scenarios
### Configure Tailwind CSS for an application with non-buildable libraries as dependencies ### Configure Tailwind CSS for an application with non-buildable libraries as dependencies
In workspaces with a single application that's consuming non-buildable libraries (libraries without a `build` target), In workspaces with a single application that's consuming non-buildable libraries (libraries without a `build` target),
you only need to configure Tailwind CSS in the application. You can do so by you only need to configure Tailwind CSS in the application. You can do so by either generating the application with
either [generating the application with Tailwind CSS already configured](#generate-an-angular-application-with-tailwind-css-pre-configured) Tailwind CSS already configured or by adding Tailwind CSS to an existing application as shown in a
or [previous section](#generating-or-adding-tailwind-css-support-to-angular-projects).
by [adding Tailwind CSS to an existing application](#add-tailwind-css-to-an-existing-angular-application-buildable-library-or-publishable-library)
.
In this scenario, the libraries will be processed as part of the application build process and therefore, the In this scenario, the libraries will be processed as part of the application build process and therefore, the
application's configuration for Tailwind CSS will be used. application's configuration for Tailwind CSS will be used.
@ -222,46 +159,15 @@ The `content` property shouldn't be specified in the preset because its value is
Add the project configuration for the project: Add the project configuration for the project:
If using the workspace configuration v2:
```jsonc {% fileName="angular.json or project.json" %}
{
"version": 2,
"projects": {
...
"tailwind-preset": "libs/tailwind-preset"
}
}
```
```jsonc {% fileName="libs/tailwind-preset/project.json" %} ```jsonc {% fileName="libs/tailwind-preset/project.json" %}
{ {
"projectType": "library", "projectType": "library",
"root": "libs/tailwind-preset",
"sourceRoot": "libs/tailwind-preset", "sourceRoot": "libs/tailwind-preset",
"targets": {}, "targets": {},
"tags": [] "tags": []
} }
``` ```
If using the workspace configuration v1:
```jsonc {% fileName="angular.json" %}
{
"version": 1,
"projects": {
...
"tailwind-preset": {
"projectType": "library",
"root": "libs/tailwind-preset",
"sourceRoot": "libs/tailwind-preset",
"architect": {},
"tags": []
}
}
}
```
Adjust the application's `tailwind.config.js` file to use the preset and remove the configuration that's already Adjust the application's `tailwind.config.js` file to use the preset and remove the configuration that's already
included in the preset: included in the preset:
@ -363,52 +269,33 @@ module.exports = {
Add the project configuration for the project: Add the project configuration for the project:
If using the workspace configuration v2:
```jsonc {% fileName="project.json" %}
{
"version": 2,
"projects": {
...
"tailwind-preset": "libs/tailwind-preset"
}
}
```
```json {% fileName="libs/tailwind-preset/project.json" %} ```json {% fileName="libs/tailwind-preset/project.json" %}
{ {
"projectType": "library", "projectType": "library",
"root": "libs/tailwind-preset",
"sourceRoot": "libs/tailwind-preset", "sourceRoot": "libs/tailwind-preset",
"targets": {}, "targets": {},
"tags": [] "tags": []
} }
``` ```
If using the workspace configuration v1:
```jsonc {% fileName="angular.json" %}
{
"version": 1,
"projects": {
...
"tailwind-preset": {
"projectType": "library",
"root": "libs/tailwind-preset",
"sourceRoot": "libs/tailwind-preset",
"architect": {},
"tags": []
}
}
}
```
Adjust the `tailwind.config.js` file of the different applications to use the preset and remove the configuration that's Adjust the `tailwind.config.js` file of the different applications to use the preset and remove the configuration that's
already included in the preset: already included in the preset:
```javascript {% fileName="tailwind.config.js" %} ```javascript {% fileName="apps/app1/tailwind.config.js" %}
// apps/app1/tailwind.config.js const { createGlobPatternsForDependencies } = require('@nx/angular/tailwind');
// apps/app2/tailwind.config.js const { join } = require('path');
const sharedTailwindConfig = require('../../libs/tailwind-preset/tailwind.config');
module.exports = {
presets: [sharedTailwindConfig],
content: [
join(__dirname, 'src/**/!(*.stories|*.spec).{ts,html}'),
...createGlobPatternsForDependencies(__dirname),
],
};
```
```javascript {% fileName="apps/app2/tailwind.config.js" %}
const { createGlobPatternsForDependencies } = require('@nx/angular/tailwind'); const { createGlobPatternsForDependencies } = require('@nx/angular/tailwind');
const { join } = require('path'); const { join } = require('path');
const sharedTailwindConfig = require('../../libs/tailwind-preset/tailwind.config'); const sharedTailwindConfig = require('../../libs/tailwind-preset/tailwind.config');
@ -424,8 +311,7 @@ module.exports = {
Do the same with any shared buildable or publishable library `tailwind.config.js` file: Do the same with any shared buildable or publishable library `tailwind.config.js` file:
```javascript {% fileName="tailwind.config.js" %} ```javascript {% fileName="libs/lib1/tailwind.config.js" %}
// libs/lib1/tailwind.config.js
const { createGlobPatternsForDependencies } = require('@nx/angular/tailwind'); const { createGlobPatternsForDependencies } = require('@nx/angular/tailwind');
const { join } = require('path'); const { join } = require('path');
const sharedTailwindConfig = require('../../libs/tailwind-preset/tailwind.config'); const sharedTailwindConfig = require('../../libs/tailwind-preset/tailwind.config');
@ -490,7 +376,7 @@ Add the CSS variable values to the different application styles entry point:
``` ```
If you're using a publishable library, you want to distribute it with a generated CSS that can be used by the consuming If you're using a publishable library, you want to distribute it with a generated CSS that can be used by the consuming
applications. To do so, take a look at [this section](#distribute-publishable-libraries-themes). applications. To do so, take a look at [the next section](#distribute-publishable-libraries-themes).
### Distribute publishable libraries themes ### Distribute publishable libraries themes
@ -531,7 +417,7 @@ configured.
Next, you need to configure your project to build the theme when you build the library. Edit the project configuration Next, you need to configure your project to build the theme when you build the library. Edit the project configuration
to have the following targets: to have the following targets:
```jsonc {% fileName="project.json" %} ```jsonc {% fileName="libs/lib1/project.json" %}
... ...
"build-angular": { "build-angular": {
"executor": "@nx/angular:package", "executor": "@nx/angular:package",