Using Tailwind CSS with Angular projects

The purpose of this guide is to cover how to use and configure Tailwind CSS with Angular 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 can be found on an Nx workspace.

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.

Tailwind CSS support by the Nx Angular plugin

The Nx Angular plugin provides support for Tailwind CSS v2 and v3. The support includes the following features:

A generator called @nrwl/angular:setup-tailwind that configures Tailwind CSS in an existing project.
An option --add-tailwind for the @nrwl/angular:app generator to create an application with Tailwind CSS pre-configured.
An option --add-tailwind for the @nrwl/angular:lib generator to create a library with Tailwind CSS pre-configured. This option can only be used with buildable and publishable libraries.
Ability to build buildable libraries with Tailwind CSS using the @nrwl/angular:ng-packagr-lite executor.
Ability to build publishable libraries with Tailwind CSS using the @nrwl/angular:package executor.

The generation for existing or new projects will perform the following steps:

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)
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

Note: 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.

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 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.

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 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 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 identified (therefore it needs to be a directory path within a project). It can also receive an optional glob pattern to append to each dependency source root path to conform the final glob pattern. If the glob pattern is not provided, it will default to /**/!(*.stories|*.spec).{ts,html}.

The following is an example of it being used in an application called app1:

1// apps/app1/tailwind.config.js
2const { createGlobPatternsForDependencies } = require('@nrwl/angular/tailwind');
3const { join } = require('path');
4
5module.exports = {
6  content: [
7    join(__dirname, 'src/**/!(*.stories|*.spec).{ts,html}'),
8    ...createGlobPatternsForDependencies(__dirname),
9  ],
10  theme: {
11    extend: {},
12  },
13  plugins: [],
14};

In the above, you are invoking the createGlobPatternsForDependencies utility function with the __dirname of the project root. The utility function will identify the project app1 and obtain its dependencies from the project graph. It will then create the glob patterns for each dependency and return them as an array. If app1 were to have lib1 and lib2 as dependencies, the utility function will return the following glob patterns:

1[
2  'libs/lib1/src/**/!(*.stories|*.spec).{ts,html}',
3  'libs/lib2/src/**/!(*.stories|*.spec).{ts,html}',
4];

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:

npx nx g @nrwl/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:

npx nx g @nrwl/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:

npx nx g @nrwl/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:

npx nx g @nrwl/angular:setup-tailwind my-project

You can see the available options for the above generator in its docs.

Tailwind CSS setup scenarios

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), you only need to configure Tailwind CSS in the application. You can do so by either generating the application with Tailwind CSS already configured or by adding Tailwind CSS to an existing application.

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.

Configure Tailwind CSS for an application with buildable or publishable libraries as dependencies

In workspaces where an application depends on buildable and/or publishable libraries, the application and those libraries need to share the same Tailwind CSS configuration because the libraries have a build target and therefore, they are set to be built on its own. When building the libraries, they need a Tailwind CSS configuration and to avoid inconsistencies, they all (the application and the libraries) need to share the same configuration.

To do so, we recommend using a Tailwind CSS preset and place it in a shared library.

Create a new folder libs/tailwind-preset with a tailwind.config.js file in it with your shared configuration:

1// libs/tailwind-preset/tailwind.config.js
2module.exports = {
3  theme: {
4    colors: {
5      primary: {
6        light: '#5eead4',
7        DEFAULT: '#14b8a6',
8        dark: '#0f766e',
9      },
10      secondary: {
11        light: '#bae6fd',
12        DEFAULT: '#0ea5e9',
13        dark: '#0369a1',
14      },
15      white: '#ffffff',
16      black: '#000000',
17    },
18    spacing: {
19      sm: '0.5rem',
20      md: '1rem',
21      lg: '1.5rem',
22      xl: '2rem',
23    },
24  },
25  plugins: [],
26};

Note: The content property shouldn't be specified in the preset because its value is not common for multiple projects.

Add the project configuration for the project:

If using the workspace configuration v2:

1// angular.json or workspace.json
2{
3  "version": 2,
4  "projects": {
5    ...
6    "tailwind-preset": "libs/tailwind-preset"
7  }
8}

1// libs/tailwind-preset/project.json
2{
3  "projectType": "library",
4  "root": "libs/tailwind-preset",
5  "sourceRoot": "libs/tailwind-preset",
6  "targets": {},
7  "tags": []
8}

If using the workspace configuration v1:

1// angular.json
2{
3  "version": 1,
4  "projects": {
5    ...
6    "tailwind-preset": {
7      "projectType": "library",
8      "root": "libs/tailwind-preset",
9      "sourceRoot": "libs/tailwind-preset",
10      "architect": {},
11      "tags": []
12    }
13  }
14}

Adjust the application's tailwind.config.js file to use the preset and remove the configuration that's already included in the preset:

1// apps/app1/tailwind.config.js
2const { createGlobPatternsForDependencies } = require('@nrwl/angular/tailwind');
3const { join } = require('path');
4const sharedTailwindConfig = require('../../libs/tailwind-preset/tailwind.config');
5
6module.exports = {
7  presets: [sharedTailwindConfig],
8  content: [
9    join(__dirname, 'src/**/!(*.stories|*.spec).{ts,html}'),
10    ...createGlobPatternsForDependencies(__dirname),
11  ],
12};

Do the same with any buildable or publishable library tailwind.config.js file:

1// libs/lib1/tailwind.config.js
2const { createGlobPatternsForDependencies } = require('@nrwl/angular/tailwind');
3const { join } = require('path');
4const sharedTailwindConfig = require('../../libs/tailwind-preset/tailwind.config');
5
6module.exports = {
7  presets: [sharedTailwindConfig],
8  content: [
9    join(__dirname, 'src/**/!(*.stories|*.spec).{ts,html}'),
10    ...createGlobPatternsForDependencies(__dirname),
11  ],
12};

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.

To configure Tailwind CSS for multiple applications sharing the same theme, our recommendation is to also use a Tailwind CSS preset and place it in a shared library. Please refer to the previous scenario setup and do the same configuration. You'll have to use the shared Tailwind CSS preset in the applications sharing the same theme.

To configure Tailwind CSS for multiple applications that use different themes and share common buildable or publishable libraries, our recommendation is still to use a Tailwind CSS preset and place it in a shared library. The difference is that instead of using literal CSS values for the configuration values, you would use CSS variables to allow each application to provide different values.

A key aspect in this scenario is that because the same buildable libraries are shared by multiple applications, you need to make sure those libraries use Tailwind CSS utility classes and/or theme keys that are common to all the applications that consume them.

Note: Different applications can still have some extra configuration unique to them, but the unique configuration can't be used by shared libraries, because it's not going to be available for other applications.

Note: As explained in this section, non-buildable libraries are processed as part of the application build process and therefore, they just use the same configuration the application uses.

Create a new folder libs/tailwind-preset with a tailwind.config.js file in it with your shared configuration:

1// libs/tailwind-preset/tailwind.config.js
2module.exports = {
3  theme: {
4    colors: {
5      primary: {
6        light: 'var(--primary-light)',
7        DEFAULT: 'var(--primary)',
8        dark: 'var(--primary-dark)',
9      },
10      secondary: {
11        light: 'var(--secondary-light)',
12        DEFAULT: 'var(--secondary)',
13        dark: 'var(--secondary-dark)',
14      },
15      white: 'var(--white)',
16      black: 'var(--black)',
17    },
18    spacing: {
19      sm: 'var(--spacing-sm)',
20      md: 'var(--spacing-md)',
21      lg: 'var(--spacing-lg)',
22      xl: 'var(--spacing-xl)',
23    },
24  },
25  plugins: [],
26};

Note: The content property shouldn't be specified in the preset because its value is not common for multiple projects.

Add the project configuration for the project:

If using the workspace configuration v2:

1// angular.json or workspace.json
2{
3  "version": 2,
4  "projects": {
5    ...
6    "tailwind-preset": "libs/tailwind-preset"
7  }
8}

1// libs/tailwind-preset/project.json
2{
3  "projectType": "library",
4  "root": "libs/tailwind-preset",
5  "sourceRoot": "libs/tailwind-preset",
6  "targets": {},
7  "tags": []
8}

If using the workspace configuration v1:

1// angular.json
2{
3  "version": 1,
4  "projects": {
5    ...
6    "tailwind-preset": {
7      "projectType": "library",
8      "root": "libs/tailwind-preset",
9      "sourceRoot": "libs/tailwind-preset",
10      "architect": {},
11      "tags": []
12    }
13  }
14}

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:

1// apps/app1/tailwind.config.js
2// apps/app2/tailwind.config.js
3const { createGlobPatternsForDependencies } = require('@nrwl/angular/tailwind');
4const { join } = require('path');
5const sharedTailwindConfig = require('../../libs/tailwind-preset/tailwind.config');
6
7module.exports = {
8  presets: [sharedTailwindConfig],
9  content: [
10    join(__dirname, 'src/**/!(*.stories|*.spec).{ts,html}'),
11    ...createGlobPatternsForDependencies(__dirname),
12  ],
13};

Do the same with any shared buildable or publishable library tailwind.config.js file:

1// libs/lib1/tailwind.config.js
2const { createGlobPatternsForDependencies } = require('@nrwl/angular/tailwind');
3const { join } = require('path');
4const sharedTailwindConfig = require('../../libs/tailwind-preset/tailwind.config');
5
6module.exports = {
7  presets: [sharedTailwindConfig],
8  content: [
9    join(__dirname, 'src/**/!(*.stories|*.spec).{ts,html}'),
10    ...createGlobPatternsForDependencies(__dirname),
11  ],
12};

Add the CSS variable values to the different application styles entry point:

1/* apps/app1/src/styles.css */
2@tailwind base;
3@tailwind components;
4@tailwind utilities;
5
6:root {
7  /* Colors */
8  --primary-light: #5eead4;
9  --primary: #14b8a6;
10  --primary-dark: #0f766e;
11  --secondary-light: #bae6fd;
12  --secondary: #0ea5e9;
13  --secondary-dark: #0369a1;
14  --white: #ffffff;
15  --black: #000000;
16
17  /* Spacing */
18  --spacing-sm: 0.5rem;
19  --spacing-md: 1rem;
20  --spacing-lg: 1.5rem;
21  --spacing-xl: 2rem;
22}

1/* apps/app2/src/styles.css */
2@tailwind base;
3@tailwind components;
4@tailwind utilities;
5
6:root {
7  /* Colors */
8  --primary-light: #a5b4fc;
9  --primary: #6366f1;
10  --primary-dark: #4338ca;
11  --secondary-light: #e9d5ff;
12  --secondary: #a855f7;
13  --secondary-dark: #7e22ce;
14  --white: #ffffff;
15  --black: #000000;
16
17  /* Spacing */
18  --spacing-sm: 1rem;
19  --spacing-md: 1.5rem;
20  --spacing-lg: 2rem;
21  --spacing-xl: 3rem;
22}

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

The purpose of publishable libraries is to distribute them outside of the workspace. As such, they should provide the CSS for their components so they can be used by the applications consuming them.

To build and share a theme, you can create a theme file in the library like the following:

1/* libs/lib1/src/styles/my-theme.css */
2@tailwind components;
3@tailwind utilities;
4
5/* You can omit this if you're not using CSS variables */
6:root {
7  /* Colors */
8  --primary-light: #5eead4;
9  --primary: #14b8a6;
10  --primary-dark: #0f766e;
11  --secondary-light: #bae6fd;
12  --secondary: #0ea5e9;
13  --secondary-dark: #0369a1;
14  --white: #ffffff;
15  --black: #000000;
16
17  /* Spacing */
18  --spacing-sm: 0.5rem;
19  --spacing-md: 1rem;
20  --spacing-lg: 1.5rem;
21  --spacing-xl: 2rem;
22}

Note: This section assume you've already followed one of the previous sections setup and have the library with Tailwind CSS configured.

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:

1...
2"build-angular": {
3  "executor": "@nrwl/angular:package",
4  "outputs": ["dist/libs/lib1"],
5  "options": {
6    "project": "libs/lib1/ng-package.json",
7    "tailwindConfig": "libs/lib1/tailwind.config.js"
8  },
9  "configurations": {
10    "production": {
11      "tsConfig": "libs/lib1/tsconfig.lib.prod.json"
12    },
13    "development": {
14      "tsConfig": "libs/lib1/tsconfig.lib.json"
15    }
16  },
17  "defaultConfiguration": "production"
18},
19"build-lib": {
20  "executor": "@nrwl/workspace:run-commands",
21  "outputs": ["dist/libs/lib1"],
22  "configurations": {
23    "production": {
24      "commands": [
25        "nx run lib1:build-angular:production",
26        "tailwindcss -c libs/lib1/tailwind.config.js -i ./libs/lib1/src/styles/my-theme.css -o ./dist/libs/lib1/themes/my-theme.css -m"
27      ]
28    },
29    "development": {
30      "commands": [
31        "nx run lib1:build-angular:development",
32        "tailwindcss -c libs/lib1/tailwind.config.js -i ./libs/lib1/src/styles/my-theme.css -o ./dist/libs/lib1/themes/my-theme.css"
33      ]
34    }
35  },
36  "defaultConfiguration": "production"
37},
38"build": {
39  "executor": "@nrwl/workspace:run-commands",
40  "outputs": ["dist/libs/lib1"],
41  "configurations": {
42    "production": {
43      "commands": [
44        "rm -rf dist/libs/lib1",
45        "nx run lib1:build-lib:production"
46      ],
47      "parallel": false
48    },
49    "development": {
50      "commands": [
51        "rm -rf dist/libs/lib1",
52        "nx run lib1:build-lib:development"
53      ],
54      "parallel": false
55    }
56  },
57  "defaultConfiguration": "production"
58},
59...

In the above, you are configuring the library build and the Tailwind CSS processing to happen in parallel. Also, you are going to disable the automatic deletion of the output folder that ng-packagr does because that can cause the theme to be deleted. Instead, you configured the build target to delete the output folder and then kick off the library build.

Note: You can have more themes and simply add them to be built in the build-lib target commands.

Update the libs/lib1/ng-package.json file to set the deleteDestPath property to false:

1{
2  ...
3  "deleteDestPath": false
4}

You can now build the library and the theme CSS will be generated in the output folder as expected.

One important thing to keep in mind is that if you use the default Tailwind CSS utility classes and distribute your theme with them, there can be conflicts with consumer applications that also use Tailwind CSS. To avoid this, you have a couple of options:

Add a unique prefix to your Tailwind CSS utility classes.
Create unique CSS classes for your components and theme in general using a Tailwind CSS directive like @apply or a function like theme().

Note: If you decide to use a unique prefix, remember to change the utility classes used in your components to use the prefix.