Forem: Leosvel Pérez Espinosa

Set up Tailwind CSS with Angular in an Nx workspace

Leosvel Pérez Espinosa — Fri, 28 Jan 2022 15:18:44 +0000

Tailwind CSS is a utility-first CSS framework packed with a lot of good functionality out of the box while providing a high level of customization. It has gained a lot of attention since it came out and it’s a good option when it comes to styling our applications.

In this blog post, we are going to see how we can use Tailwind CSS with Angular in an Nx monorepo. We are going to be looking at different scenarios and how to approach them.

Let’s get started!

Please note that this blog post is not meant to be a Tailwind CSS or Angular tutorial. The purpose is to show how to use them together and how Nx can help to improve the developer experience and expand the native Angular capabilities when working with Tailwind CSS.

What are we going to build?

The final result of what we are going to be building can be found in this Github repository: https://github.com/leosvelperez/angular-tailwind-nx.

We are going to create 2 simple applications with the following layout:

We’ll start by creating one application with the required markup and Tailwind CSS utility classes to achieve the above layout. Then, we’re going to leverage Nx’s library support and extract some common UI components into 2 different shared libraries:

a regular non-buildable library containing the header,
a buildable library containing the card elements.

At that point, we’ll create the second application using the components exposed by those shared libraries. Finally, we’ll extract the button elements to a publishable library and adjust both applications to use them.

The idea is to show how different applications can still use the same components and have them styled differently using Tailwind CSS. Both applications in this blog post will share the same layout, but the approach explained here would apply to applications with different layouts sharing the same UI components.

Discussing the different types of libraries and the motivation to use them goes beyond the scope of this blog post. We’ll use the three different types just to showcase how to use Tailwind CSS with each of them. To know more about them, please check https://nx.dev/structure/creating-libraries and https://nx.dev/structure/buildable-and-publishable-libraries.

Setting up the Nx workspace

First things first! We start by creating a new Nx workspace where our applications and libraries will be located. To do that, we can run:

❯ npx create-nx-workspace@latest angular-tailwind-nx --pm=yarn
✔ What to create in the new workspace · angular
✔ Application name                    · app1
✔ Default stylesheet format           · css
✔ Use Nx Cloud? (It's free and doesn't require registration.) · No

Passing the --packageManager (or --pm) flag allows us to change the package manager. If not passed, it defaults to npm.

The above command creates a workspace called angular-tailwind-nx and asks us a few questions to help us set up the workspace. We chose the angular preset, provided app1 for the initial Angular application name, chose css as the stylesheet to use, and this time chose not to use Nx Cloud but feel free to opt-in to use the Nx Cloud free tier to benefit from distributing the computation caching of your projects.

Any of the stylesheet options can be used. Also, using Nx Cloud or not doesn’t affect setting up Tailwind CSS.

Now that we have a workspace with an Angular application ready to be used, let’s start adding some Tailwind CSS magic!

Adding Tailwind CSS

Angular added native support for building applications using Tailwind CSS a while ago. Still, we need to set it up in the workspace, and to do so, we can use the @nrwl/angular:setup-tailwind generator by simply running:

npx nx generate @nrwl/angular:setup-tailwind app1

The above command will do a few things for us:

It will check if tailwindcss is already installed and if not installed, it will install the necessary packages (tailwindcss, postcss and autoprefixer)
It will create a tailwind.config.js file in the project root with the default configuration to get started (specific to the installed version)
It will recognize the project type and for applications, it will update the application styles entry point file located at apps/app1/src/styles.css by including the Tailwind CSS base styles

The above generator supports Tailwind CSS v2 and v3.

Let’s take a look at the generated apps/app1/tailwind.config.js file:

We can see the content property is configured to scan for all the HTML and TypeScript files within our application and besides that, there’s also a call to a function called createGlobPatternsForDependencies. This is a pretty handy function that will identify the dependencies of the application and return the glob patterns for them. This ensures that Tailwind CSS utility classes that are used in the application’s dependencies are also taken into account and included in the final CSS of the application.

Instead of using the createGlobPatternsForDependencies, we could just add the libs/**/* glob pattern that captures all libraries, but that could lead to bundling more CSS than needed in monorepos with multiple applications. This would happen because all applications would be scanning all libraries, regardless of whether they are dependencies or not. Such a glob pattern could also lead to scaling issues in large monorepos due to the amount of libraries to scan.

We can also see that the generator updated the apps/app1/src/styles.css file with the Tailwind CSS bases styles:

And that’s all we need. We can now go ahead and add our custom theme and layout to achieve the desired design.

Adding a custom theme and the application markup

First, we are going to update the theme section of the generated apps/app1/tailwind.config.js. We are going to overwrite the Tailwind CSS default theme and provide the custom palette of colors and spacing of our theme to be used throughout the application:

Next, we update the apps/app1/src/app/app.component.html file with the required markup and several Tailwind CSS utility classes to style the application with the look & feel we are looking for:

With all set, let’s see it in action by running:

npx nx run app1:serve

Visiting https://localhost:4200 in your browser should show the application looking like the following screenshot:

That’s it! We have successfully created our application to fulfill the requirements we had. Next, we are going to start extracting pieces of the UI into shared libraries to reuse them with the second application.

Tailwind CSS and Angular libraries in an Nx workspace

Before extracting our UI components into libraries, we need to take a step back and make sure we understand how Tailwind CSS works and the implications of the different types of libraries in an Nx workspace.

From Tailwind CSS docs:

Tailwind CSS works by scanning all of your HTML files, JavaScript components, and any other templates for class names, generating the corresponding styles and then writing them to a static CSS file.

Any project can use the Tailwind CSS CLI or PostCSS with the tailwindcss plugin to scan the relevant files in the project and collect the usage of the Tailwind CSS utility classes, functions, and custom CSS directives (custom CSS at-rules). With that information, the final CSS styles are generated.

Angular uses PostCSS to support Tailwind CSS. As we saw in a previous section, with the help of an Nx generator, it’s pretty straightforward to configure a Tailwind CSS for applications. Libraries can also be easily configured, but there are some nuances regarding how they are processed and whether they need to be configured or not.

In an Nx workspace, a regular library (non-buildable and non-publishable) is just a slice of an application that is only built as part of the build process of an application that consumes it. Because of that, as long as the application that consumes it has Tailwind CSS configured, the library code will be processed as expected even though the library itself doesn’t have a Tailwind CSS configuration. In fact, adding a tailwind.config.js file to the library won’t have any effect whatsoever (it’ll be ignored) because the library is never built on its own.

On the other hand, buildable and publishable libraries are meant to be built on their own and their compiled output to be shared with the consumers. Therefore, they need to be able to process any Tailwind CSS directive or function (e.g. @apply, theme()) when they are built. If no Tailwind CSS directive or function is used, then the configuration is not needed.

Providing the configuration to a buildable or publishable library that doesn’t need it adds some unnecessary overhead to the build process. The executor will still load the configuration and the PostCSS plugin will process the stylesheets unnecessarily.

How does this work?

Tailwind CSS produces the relevant CSS code where the following directives and functions are used:

@tailwind
@apply
theme()
screen()

When the PostCSS plugin processes a file containing these, it processes them and produces the corresponding CSS code based on the provided configuration. If none of the above is used in a buildable or publishable library, no CSS is generated, and therefore, no configuration is needed. The actual CSS will be generated when building the application consuming those libraries.

To know more about the above directives and functions you can take a look at https://tailwindcss.com/docs/functions-and-directives.

But we do use Tailwind CSS utility classes in the libraries and CSS needs to be generated for them. So, how is the CSS generated for those classes if the libraries are not configured?

If we recall from a previous section, in our application’s tailwind.config.js file, we have the following:

The content property of the configuration tells Tailwind CSS where to look for usages of utility classes. When the PostCSS plugin finds a file using the @tailwind directive, it will collect all the utility classes for the layer specified by the directive in the files matching the glob patterns set in the content property of the configuration, and it will produce the CSS replacing the directive. It’s worth noting that the PostCSS plugin only scans the files collecting the utility classes that are used, it doesn’t process them. Only the file containing the @tailwind directive is updated with the resulting CSS.

Since we have our application configured to scan the relevant files within itself and also within its dependencies, the utility classes used in the libraries that are dependencies of the application will be picked up correctly and the CSS will be generated for them.

It’s important to note that the support for Tailwind CSS for Angular libraries is only available using the @nrwl/angular:ng-packagr-lite executor for buildable libraries and the @nrwl/angular:package executor for publishable libraries.

Below is a small decision tree to check whether a Tailwind CSS configuration is needed for your library in an Nx workspace:

Extracting the header into a library

Our application is looking good. At the same time, there’s a great opportunity to reuse some of its components in another application. Therefore, we are going to extract the shared components into several shared libraries.

The applications of this blog post are very simple and it’s probably not worthy to extract the components into multiple libraries. We are doing it for illustrative purposes to cover the different scenarios we might find in real-life applications.

We’ll start by extracting the header of the application into a reusable component and placing it into a library. To do so, we start by creating a new Angular library in our workspace by running:

npx nx generate @nrwl/angular:lib lib1

Next, we create the component for the header in the library we just generated and we export it so it can be imported by consumers:

npx nx generate @nrwl/angular:component header --project=lib1 --export

Add the markup for the header to the libs/lib1/src/lib/header/header.component.html:

Import Lib1Module into our application’s AppModule:

And finally, replace the existing markup for the header in the apps/app1/src/app/app.component.html file with the newly created header component and leaving the rest of the file as-is:

At this point, if we serve again the application, everything should still be working the same way as before. We successfully extracted the header into a shared library and made it reusable.

Extracting the card into a buildable library

Similar to the previous section we are going to start by creating a new library to add the card component to. The only difference is that this library is going to be buildable.

If you are not aware of what buildable libraries are or what problem do they intend to solve, please make sure to read https://nx.dev/ci/incremental-builds and particularly pay attention to when should they be used.

Run the following command to generate the library:

npx nx generate @nrwl/angular:lib lib2 --buildable

Next, we configure Tailwind CSS for it:

npx nx generate @nrwl/angular:setup-tailwind lib2

As explained in a previous section when we did the same for the application, the above command will install any required dependencies if needed, create the tailwind.config.js file and in the specific case of libraries, it will also add the tailwindConfig property to the build target of the project configuration.

Angular applications, buildable and publishable libraries can be created with Tailwind CSS support with a single command. We’ll see that in the upcoming section. The @nrwl/angular:setup-tailwind generator is used to add Tailwind CSS support to existing projects.

Then, we create the card component:

npx nx generate @nrwl/angular:component card --project=lib2 --export

We add the component to the library entry point located in libs/lib2/src/index.ts:

Then, we update the card component files to provide the desired functionality:

Import Lib2Module into our application’s AppModule:

And finally, replace the existing markup for the cards in the apps/app1/src/app/app.component.html file with the newly created card component:

With that in place, we can serve the application and it should be working exactly as before, but our application is still not fully set up to consume the library build output. As it stands right now, when the application that’s consuming it is built, the library will be built together with it and its files will be processed as part of the application build pipeline.

To finish the buildable library setup, we can follow the instructions in https://nx.dev/ci/setup-incremental-builds-angular#adjust-the-app-executor. We need to install the @nrwl/web package, change the application build target executor to @nrwl/angular:webpack-browser, and change the application serve target executor to @nrwl/web:file-server:

yarn add -D @nrwl/web@latest

You can now go ahead and serve the application to check everything is working as expected. You should see the buildable library being built on its own before the application is built and served.

The @nrwl/web:file-server executor uses the http-server package to serve the built artifacts of our application. This is a lightweight HTTP server and it doesn’t do things like live-reload or HMR. Be sure to refresh your browser while making changes to see them reflected.

Using Tailwind CSS directives and functions in buildable libraries

Our application is consuming a buildable library and still working as intended, but if we think about it, we didn’t configure our theme in the library’s tailwind.config.js file. So, how is it still working?

If we go back to the decision tree shared in a previous section, we’ll see that a buildable library only needs a Tailwind CSS configuration if we use a Tailwind CSS directive or function. As of right now, our library is not using any. We are just using some utility classes and those are processed correctly as part of the application build. You could go ahead and delete the tailwind.config.js file from the library and check that everything still works the same (if you do, please make sure to restore it before we continue).

Next, we are going to refactor our newly created card component to make use of some of these directives and functions and see the implications.

Update the card component files content as shown below:

We created some CSS classes where we are applying the same styles we had in the component template. We are applying those styles by using a combination of the @apply directive and the theme function.

Please note we are not recommending creating CSS classes for scenarios like the above. The card component is already a reusable component and there’s no need to extract CSS classes to style it. We are only extracting these classes to showcase how Tailwind CSS directives and functions can be correctly processed in buildable libraries. Make sure to check out the Tailwind CSS recommendations for reusing styles.

If we now serve our application (or build the library), we’ll find ourselves with the following error:

------------------------------------------------------------------------------
Building entry point '@angular-tailwind-nx/lib2'
------------------------------------------------------------------------------
/angular-tailwind-nx/libs/lib2/src/lib/card/card.component.css:2:3: The `p-lg` class does not exist. If `p-lg` is a custom class, make sure it is defined within a `@layer` directive.

This is to be expected. The library build is failing because now we are using some Tailwind CSS directives and functions, and therefore, those directives and functions are being processed within the library context. Since we haven’t touched the tailwind.config.js file, Tailwind CSS doesn’t know about our custom theme.

To solve the issue, we need to configure the library to be aware of our custom theme so it can process the library’s files correctly. Let’s update the theme property of the libs/lib2/tailwind.config.js file to match our application theme:

Now, we should see our application working correctly if we serve it again.

Sharing the Tailwind CSS configuration between the application and the buildable library

Though we have successfully solved the issue and our workspace now has a library that can be built on its own and be cached, the experience is not great. We had to duplicate the application configuration in the buildable library. This introduces a maintainability concern and it will most likely be a cause for errors due to having to maintain them in sync. Also, we only have one buildable library in this small example, but imagine a real-life scenario where hundreds of these libraries need to be kept in sync. A nightmare!

Well, no need to fret!

If we think about it, the same reasoning behind creating shared libraries applies to this. We just need to share the Tailwind CSS configuration. To do so, we have a couple of options:

Create a shared file containing and exporting the theme so it can be imported by every project’s tailwind.config.js file.
Create a Tailwind CSS preset to expose a base configuration for your projects.

The last option is the better one. We can take advantage of the Tailwind CSS built-in support for defining a base configuration to be reused across different projects. The first option is almost the same, with the difference that we have to manually handle merging the configurations.

We’ll go ahead and create a Tailwind CSS preset and we’ll then use it in our projects. Start by creating a tailwind.config.js file in the root of the workspace with the following content:

We just added the configuration that is common to our projects to use as a base in each of them. Next, we need to add the preset configuration to each project.

Update both apps/app1/tailwind.config.js and libs/lib2/tailwind.config.js files to match the following:

Notice how we added the preset and removed almost all the configuration because it’s already defined in the preset.

That’s all it takes. You can go ahead and serve the application (or refresh the browser if you are already serving it) to check everything is running correctly.

Sharing the Tailwind CSS preset in a library

We now only have to maintain our theme in a single place as opposed to keeping in sync the configuration of all the different projects. But we can still improve the experience. As it stands, if you now make a change on the tailwind.config.js file located at the root of the workspace (our preset), the file server doesn’t pick up the change and therefore, it doesn’t rebuild the affected projects.

This happens because the file server is watching for changes under the apps and libs folders. The preset configuration is not under those directories, it’s in the root of the workspace.

It would be better if we place the preset configuration in a small shared library. By doing that, we not only solve the issue regarding detecting changes on it, but we also make its library appear on the Nx project graph, and with that, we benefit from all the goodies associated with the project graph (affected commands, enforcing module boundaries constraints, etc.).

This library is only going to contain the tailwind.config.js file and no targets in the project configuration. There’s no generator among the Nx core plugins that generate such an empty library. We could use one of the library generators and remove some content, but let’s create it manually.

Start by creating a new folder libs/tailwind-preset and moving the tailwind.config.js file we created in the previous section at the root of the workspace to that folder.

Next, add the project to the angular.json:

Create the configuration for the project in libs/tailwind-preset/project.json:

And finally, adjust both apps/app1/tailwind.config.js and libs/lib2/tailwind.config.js files to import the preset from the correct location:

Once again, if we serve our application everything should still be working as expected, but now our file server will pick up the changes made to the Tailwind CSS preset configuration.

Also, if we visualize the workspace projects we’ll see how app1 and lib2 now have a dependency on tailwind-preset:

Creating the second application

We are now at a stage where we can develop our second application without having to duplicate the common functionality. So, before going ahead and distributing our buttons in a publishable library, let’s first create the second application to see how we can reuse what we have been putting into libraries.

There’s one important thing to note though, this new application will have a different theme.

Generate the application by running the following command:

npx nx generate @nrwl/angular:app app2 --addTailwind --style=css --routing=false

The above command will generate the new application and it will configure Tailwind CSS as well. Using the --addTailwind flag will instruct the application generator to automatically run the @nrwl/angular:setup-tailwind generator when creating a new application.

The --addTailwind flag is available in both @nrwl/angular:app and @nrwl/angular:lib generators.

Let’s now update the application to use the shared components and achieve the layout we are after. Start by updating the apps/app2/src/app/app.module.ts to import Lib1Module and Lib2Module:

Next, update the apps/app2/src/app/app.component.html file with the required markup and Tailwind CSS utility classes to achieve our application’s layout and using the component exported by the shared libraries we previously created:

Like we did with app1, we also need to update the build and serve targets configuration for app2 to be able to consume the buildable library compiled output. We do so by updating the app2 configuration located in the apps/app2/project.json file:

Last but not least, we need to configure Tailwind CSS with our custom theme for app2. We’ll do that by updating the apps/app2/tailwind.config.js file with the following:

Now that we have the second application configured, let’s run it:

npx nx run app2:serve

You can pass a --port=4201 to the above command to run it in a different port if it’s in use or if you want to have both applications running side-by-side.

Now, open your browser and navigate to it where you should see the application looking like the following screenshot:

That does indeed look different, but something is off. The card background color is not right, it’s still the same used for app1 even though we provided a different theme. Also, some of the spacing for the elements within the card doesn’t seem to have changed according to our configuration.

What is going on here?

You might have realized a couple of things by now:

The card component comes from lib2 which is a buildable library and as such, it’s built on its own using its own Tailwind CSS configuration
app1 and lib2 use a Tailwind CSS preset to share the common configuration, while app2 is adding its own

So, the first bullet point above would explain why the card component looks like the one rendered using the theme for app1. But that’s not exactly what we are seeing, the buttons inside the card look different than what we have in app1. This is explained by the fact that the buttons are styled without using any Tailwind CSS directive or function, they just use utility classes, so the CSS for them is generated in the app2 build using the application configuration. The rest of the card does use directives and functions, so the CSS for that is generated in the lib2 build using the library configuration.

Also, we previously created a Tailwind CSS preset so we could share the base configuration among different projects. The problem is that all those projects shared a common theme, but app2 requires a different one, so we can’t just use the preset as it is right now.

So, how do we solve this?

Enter CSS variables!

We can configure the Tailwind CSS preset to use CSS variables. This will allow each application to provide its own values for the variables and therefore, it enables us to have multiple themes using the same Tailwind CSS configuration.

Let’s update our preset in the libs/tailwind-preset/tailwind.config.js file to use CSS variables instead of literal values:

Next, we update the apps/app2/tailwind.config.js file to remove the explicit theme configuration and add the preset instead:

Since our preset no longer has any literal values for the theme properties, we need to set the values for the CSS variables in the application. Edit the apps/app2/src/styles.css file with the values for the theme variables:

We need to do the same for app1. Edit the apps/app1/src/styles.css file with the values for the theme variables:

Let’s serve again app2 and navigate to it to check the results of our changes:

Now we are talking!

This is what we wanted to see. Also app1 is still working as expected with its different theme. We are successfully styling two different applications with different themes while sharing some UI components and using the same Tailwind CSS base configuration.

Extracting the button into a publishable library

Now that both our applications are looking great, we want to share our awesome buttons with the community. So we are going to create a button component in a publishable library to be able to distribute it.

First, we create the publishable library with Tailwind CSS support:

npx nx generate @nrwl/angular:lib lib3 --publishable --importPath=@angular-tailwind-nx/lib3 --addTailwind

Then, we update the libs/lib3/tailwind.config.js to use the shared preset:

Then, we create the button component:

npx nx generate @nrwl/angular:component button --project=lib3 --export

We add the component to the library entry point located in libs/lib3/src/index.ts:

Then, we update the button component files to provide the desired functionality:

Next, we need to update the card component in lib2 to use the button component. Import Lib3Module into Lib2Module:

And finally, we replace the existing markup for the button in the libs/lib2/src/lib/card/card.component.html file with the new button component:

Once more, we can check both applications and make sure everything is still working and nothing was affected by the changes made.

Distributing the publishable library styles

The recently created publishable library is already being used successfully by both applications, but it’s still not ready for distribution. If we were to share it now, external consumers will need to provide their own CSS for it because the library itself is not bundling any CSS with the styling for the button. We only used some Tailwind CSS utility classes and as we have seen throughout this blog post, the CSS for them is generated in files containing @tailwind directives (normally in application style entry points).

Within the workspace, it works as expected because the applications consuming it use the same shared Tailwind CSS preset and their dependencies are included in the content of their configuration.

The library needs to contain everything that’s needed for it to work and to achieve this, we are going to do something we already did with our buildable library: create our own classes using the @apply directive.

As we learned in a previous section, the @apply directive will be transformed into the CSS corresponding to the Tailwind CSS classes being applied. Thanks to this, our button component will contain the CSS needed to style it.

Go ahead and update the button component files with a new CSS class for the button:

I used the prefix atn (initials of Angular, Tailwind CSS, and Nx) for the CSS class name to prevent potential name collisions with the consumers' applications CSS.

Also, let’s update the libs/lib3/src/lib/button/button.component.ts file to set the component’s encapsulation to ViewEncapsulation.None to allow consumers to overwrite its styles more easily:

If we build our library now, the styles for the button component will be correctly generated, but because we are using CSS variables for our theme, consumers would still need to provide their own values for them before they can use it.

We need to provide an initial theme that sets those CSS variables so the library components can be consumed without any additional setup. Actually, we are going to generate a couple of theme options so we can see how multiple themes can be provided.

Let’s start by creating a libs/lib3/src/styles/teal.css theme file where we are going to import the Tailwind CSS components and utilities layers and define the values for the CSS variables of our theme:

Notice that we didn’t include the base layer like we have done so far in the applications style entry points. This is because this is a component library and the base layer generates a set of application-wide base styles and that’s not what we want to generate here.

Next, we generate our second theme by creating the libs/lib3/src/styles/indigo.css theme file with different values for the CSS variables:

With that in place, we now need to make sure those theme files are processed when we build the library. The @nrwl/angular:package executor is powered by the ng-packagr package to build the library. This is a tool recommended by Angular to ensure libraries are distributed using the Angular Package Format. Unfortunately, it doesn’t have native support for building standalone stylesheets that are not referenced by a component, so we need to configure it ourselves.

To do so, we are going to use the Tailwind CSS CLI to process our stylesheets when the library is built and we’ll do it in parallel since they don’t depend on each other. One aspect to consider is that the @nrwl/angular:package executor will delete the destination folder before building. When running both processes in parallel, the styles might be generated first and then the directory containing them is deleted by the @nrwl/angular:package executor. Therefore, we are going to disable that behavior and we are going to control when to delete the destination folder to avoid any issues.

Another thing to consider is that the Tailwind CSS CLI only supports processing one file at a time, it doesn’t accept glob patterns or directories. We’ll need to run a command per theme in our library.

To orchestrate this, we are going to make the following changes to the lib3 project configuration:

Rename the existing build target to build-angular
Create a build-themes target that runs, in parallel, the Tailwind CSS CLI for every theme in our library
Create a build-lib target that runs, in parallel, the build-angular and build-themes targets
Create a build target that first, deletes the destination folder, and then runs the build-lib target

Edit the project configuration for the lib3 project located in the libs/lib3/project.json file with the changes described above and shown below:

The only thing remaining is to update the libs/lib3/ng-package.json to prevent the Angular build to delete the destination folder. We do that by setting the deleteDestPath option to false:

We can now build the library by running:

npx nx run lib3:build

If we check the output folder dist/libs/lib3, we’ll see there’s a themes folder in it with a couple of files indigo.css and teal.css:

These theme files can now be used by the consumers of our library to properly style the components exposed by it. All they would need to do is to import one of those themes into their application styles entry point or index.html file.

They can also customize the included themes by overwriting any of the CSS variables of the theme or the specific styles of the atn-button CSS class.

Conclusion

We covered a lot in this article and hopefully, it gave a good walkthrough over the different scenarios we might find ourselves when using Angular and Tailwind CSS in an Nx workspace.

Doing a quick recap, we learned:

How to add support for Tailwind CSS in existing Angular projects using an Nx generator
How to create Angular projects with Tailwind CSS already configured using an Nx generator
How to share Tailwind CSS configuration among an application and its dependencies using presets
How to share Tailwind CSS configuration among multiple applications and their dependencies while still being able to have different styles
How to create and distribute multiple themes in an Angular publishable library using Tailwind CSS

Creating my personal website with Astro, Tailwind CSS, and Nx

Leosvel Pérez Espinosa — Tue, 25 Jan 2022 12:26:51 +0000

It is certainly something I have been thinking about doing for quite some time, but I never really went for it until now. Several reasons have deterred me in the past from creating a personal website, and while some of them might still be valid, I decided to give it a go and create something it could push me to try to create more content and a place where I can experiment with different technology stacks.

TL;DR

You can take a look at the source code in the website's GitHub repository.

Technology stack

I have been working with Angular for several years and it would have been the most comfortable choice, but I wanted to try something new and different; after all, that was one of the main reasons I decided to create my personal website.

A few months ago, I came across Astro, a modern static site builder that promises to deliver great performance by shipping zero JavaScript by default. With other interesting features like the ability to use other frameworks, on-demand partial hydration, and Markdown support, it immediately caught my attention and became my first choice.

I also wanted to use Tailwind CSS. I've previously played with it and I really like its flexibility and how easy and fast you can prototype and style your site. I'm not a designer and I'm not a creative person, so I particularly like the ability to quickly try things out and see how they look to find out what I like the most.

For the hosting, I decided to go with Cloudflare Pages. It has the features I was looking for and more: automatic deployments from GitHub, preview PRs, ease of use, etc. There are several other great choices out there (Netlify, Vercel, and GitHub Pages to name a few) that I'll most likely be trying out in the future.

Last but not least, I chose to use Nx to benefit from its generation features, smart build system, and the many different features it provides. In reality, "chose" is not the right word here. I was always going to use Nx from the start. I can't see myself not using it for any project.

Note: Though it was not necessary, I took the opportunity to create an Nx plugin called @nxtensions/astro that adds first-class support for Astro (maybe a story for a different blog post).

To summarize, this is the stack I ended up with:

Astro: a modern static site builder.
Tailwind CSS: a utility-first CSS framework.
Cloudflare Pages: a JAMstack platform for frontend developers to collaborate and deploy websites.
Nx: a next generation build system with first class monorepo support and powerful integrations.

Astro basic features

Before diving into creating the required pages and components, let's have a quick overview of some of the basic Astro features I used to build the website.

Components

Astro comes with its own component syntax. Any file with the .astro extension represents a single Astro component and it follows the Single-File Component (SFC) pattern by containing the HTML, CSS, and JavaScript needed to render the component in the same file.

The Astro component syntax is very similar to HTML and JSX. In fact, it's a superset of HTML and every component must include an HTML template.

Astro also has the concept of a Frontmatter component script to build dynamic components. The component script natively supports JavaScript and Typescript and it will only be processed at build time.

Pages

An Astro page is just a special type of component with additional responsibilities. While a component can return partial HTML templates, pages must return a full HTML document. Astro supports the .astro and .md files for pages, and they should be placed in the src/pages directory (or the directory specified in the configuration pages option).

Routing

Astro uses an approach called file-based routing to generate the application URLs at build time based on the pages directory structure. It supports static routes as well as dynamic routes. You can check more about this in the docs.

Creating an Nx workspace with an Astro application

Having a clearer grasp of Astro's features, I started by creating a new empty Nx workspace by running the following command:

npx create-nx-workspace@latest leosvel-dev --preset=empty --pm=yarn

Note: I specified the --pm=yarn option to use Yarn as the package manager but this is not a requirement. You can use other package managers.

Once the workspace was generated, I navigated to it and installed the @nxtensions/astro plugin:

cd leosvel-dev && yarn add -D @nxtensions/astro@latest

Finally, I proceeded to generate the Astro application by running:

npx nx g @nxtensions/astro:app website

I didn't choose to use any renderer (to support other frameworks) because I just wanted to use Astro components.

Tip: If you use VSCode, you can use the Nx Console extension that provides a UI for the Nx CLI. With it, you can use a GUI to run any Nx command.

At this point, I had a new Nx workspace with an Astro application properly configured and I was already able to start the Astro development server by running:

npx nx dev website

Visting http://localhost:3000 in my browser displayed the landing page that was automatically generated when I created the application.

Cleaning up application files

The generated application comes with a default landing page with some content to help get started. Before moving forward, I deleted the content of the apps/website/src/pages/index.astro file and deleted the apps/website/src/components/Tour.astro and apps/website/public/styles/home.css files.

Configuring Tailwind CSS

To configure Tailwind CSS, I started by installing the required packages:

yarn add -D tailwindcss@latest postcss@latest autoprefixer@latest

Then, I added the configuration for it in the project root:

// apps/website/tailwind.config.cjs
module.exports = {
  content: [
    './public/**/*.html',
    './src/**/*.{astro,md,js,jsx,svelte,ts,tsx,vue}',
    '../../libs/**/*.{astro,md,js,jsx,svelte,ts,tsx,vue}',
  ],
  theme: {},
};

// apps/website/postcss.config.cjs
module.exports = {
  plugins: [require('tailwindcss')],
};

Next, I proceeded to add the Tailwind CSS base styles to the existing apps/website/public/styles/global.css file:

@tailwind base;
@tailwind components;
@tailwind utilities;

Because the files in the public directory are never processed by the Astro build process, I later moved the apps/website/public/styles/global.css file out of the public directory, so it gets processed by the PostCSS plugin for Tailwind CSS. In the coming sections, I'll cover where I placed it and how this file is referenced on the website's pages.

Creating the common layout

The website currently has 3 types of pages: the landing page, the blog page, and the blog post page. All of them share a common layout consisting of a header, the main content, and a footer.

There's also a 404 page, but I'm not going to cover it here since it's a very simple page. It's a page that will appear when the user tries to access a page that doesn't exist.

Astro has a concept of Layouts. They are basically components with the specific purpose of providing a reusable page structure to reduce duplicating the same code on multiple pages.

I created a apps/website/src/layouts/BaseLayout.astro file with the following content:

---
import { Footer, Head, Header } from '@leosvel/common';

export interface Props {
  title: "string;"
  description: "string;"
  socialImage?: string;
  socialImageAlt?: string;
}

const { title: "pageTitle, description, socialImage, socialImageAlt } = Astro.props;"
const { canonicalURL } = Astro.request;
const siteName = canonicalURL.hostname;
const title = `${pageTitle} | ${siteName}`;
---

<html lang="en" class="scroll-smooth">
  <head>
    <Head {title} {description} {canonicalURL} {siteName} {socialImage} {socialImageAlt} />
  </head>

  <body class="min-h-screen w-screen bg-white flex flex-col font-mono text-white selection:bg-cyan-700 selection:text-white overflow-x-hidden">
    <Header currentPage={Astro.request.url.pathname} />

    <main class="flex flex-1">
      <slot />
    </main>

    <Footer />
  </body>
</html>

Alright! There's a lot going on there. Let's break it down to see what's going on.

The section at the top delimited by the --- lines is the Frontmatter script for the component. That's the place where we can import other components and write JavaScript/Typescript code that is going to be executed at build time. In this particular layout, I'm importing some components that we are going to be using, exporting the Props interface to define what props are expected, and finally, I'm getting a reference to those props from the Astro global object and some other values I need from the Astro.request object.

Outside of that section, we can write our HTML markup as well as include <style> and <script> tags. For this particular case, I'm defining the HTML content with the desired structure for the website's pages and some basic styling using Tailwind CSS. This is where I'm making use of the imported components and I'm passing some props for them as required.

One important thing to note is the slot tag. This element allows us to render children elements passed inside the layout when consuming it.

As you can see in the code, I'm importing several components from @leosvel/common. This is a library I created in the workspace where I placed some common components used by the different website's pages. I created the library by running:

npx nx g @nxtensions/astro:lib common

In this library, I placed the global.css file mentioned in the previous section that contains the Tailwind CSS base styles. Also, among the components created in that library, we can find the Head component, which contains metadata, scripts, and styles for the pages. This is the component that includes the global.css file so it's available for every page.

The following is the specific portion of code in the libs/common/src/lib/components/Head.astro file that includes the global styles:

...
<!-- Global styles -->
<style global>
  @import '../styles/global.css';
</style>

Creating the website's pages

Now that I had the base layout ready, it was time to use it to create some pages.

Landing page

When it comes to pages, I like to keep them clean and simple and extract their presentation content into components. This is also in line with the Nx philosophy of keeping our apps light and extracting the functionality into libraries.

I created a landing library where I placed a component with the UI of the landing page. This page is quite simple right now and as it stands, it might seem too much to have a library for a single component, but creating a library is cheap and I plan to have more things in it in the near future.

This website in general is pretty simple, so it could have been done without any library at all. However, I like splitting my projects into smaller and more focused units (libraries) and I wanted to make the most of using Astro with Nx.

The following is the source code for the landing page located in apps/website/src/pages/index.astro:

---
import Layout from '../layouts/BaseLayout.astro';
import { Landing } from '@leosvel/landing';

const title = 'Home';
const description = 'My personal website with my projects and blog.';
---

<Layout {title} {description}>
  <Landing />
</Layout>

You can notice above how I made use of the layout I created in the previous section and how I'm passing the Landing component as a child to it. This causes it to be rendered in the slot tag we previously added to the layout which is placed between the Header and Footer components. The Landing component doesn't have anything worthy of showing, it only contains the needed HTML markup and Tailwind CSS classes.

Blog page

The next page to look at is the blog page located in apps/website/src/pages/blog/index.astro. Following Astro's file-based routing approach, this page will be available at the /blog URL.

The blog page displays a list of blog posts. These blog posts are written in Markdown files and placed in the apps/website/src/data/blog-posts directory. So, I needed to get the list of blog posts and display them.

Let's have a look at the apps/website/src/pages/blog/index.astro file to see how I did it:

---
import Layout from '../../layouts/BaseLayout.astro';
import { Blog } from '@leosvel/blog';

const title = 'Blog';
const description = 'My blog with articles about web development and programming in general.';

const posts = Astro.fetchContent('../../data/blog-posts/*.md').sort(
  (a, b) => new Date(b.date).valueOf() - new Date(a.date).valueOf()
);
---

<Layout {title} {description} socialImage="/assets/blog-leosvel.dev.png" socialImageAlt="Leosvel's blog social image">
  <Blog {description} {posts} />
</Layout>

Like the landing page, it's very simple and it delegates the presentation concerns to the Blog component (located in the blog library) while providing a title and the list of posts. The interesting bit is the loading of the Markdown files with the blog posts. To do that, I used the Astro.fetchContent() helper function passing a glob to those files. This function returns an array of objects containing, among other things, the Frontmatter properties specified in the Markdown files. I used the date property to sort the posts by date in descending order.

The following is the Frontmatter script section for this blog post Markdown file:

// apps/website/src/data/blog-posts/creating-my-personal-website-with-astro-tailwindcss-and-nx.md
---
title: 'Creating my personal website with Astro, Tailwind CSS, and Nx'
description: 'How I went about creating my personal website using Astro, Tailwind CSS, and Nx.'
date: 'January 25, 2022'
heroImage: '/assets/blog/creating-my-personal-website-with-astro-tailwindcss-and-nx/hero.png'
heroImageAlt: 'Astro, Tailwind CSS, and Nx logos'
thumbnailImage: '/assets/blog/creating-my-personal-website-with-astro-tailwindcss-and-nx/thumbnail.png'
thumbnailImageAlt: 'Astro, Tailwind CSS, and Nx logos'
---

You can see the date property that is used on the blog page to sort the blog posts.

Let's also have a look at the source code portion of the Blog component where I use the received posts to display a list with a preview for each of them (the rest of the file is omitted for brevity):

// libs/blog/src/lib/components/Blog.astro
...
<section class="grid justify-center sm:grid-cols-2 lg:grid-cols-3 gap-8">
  {posts.map((post) => {
    const link = `/blog/${post.file.pathname.split('/').pop().split('.').shift()}`;

    return (
      <BlogPostPreview
        post={{
          title: post.title,
          description: post.description,
          date: post.date,
          link,
          thumbnailImage: post.thumbnailImage,
          thumbnailImageAlt: post.thumbnailImageAlt,
        }}
      />
    );
  })}
</section>
...

If you've used JSX before, this probably looks very familiar. I'm basically iterating over the posts array and creating a BlogPostPreview component for each blog post. I'm also building the link to it using the blog post Markdown file path as the URL segment. The BlogPostPreview component is a simple component that only contains the needed HTML markup and Tailwind CSS classes to display a preview of the blog post.

Blog post page

The blog post page renders the blog post content. This is a dynamic route from which many URLs will be generated (one per available blog post). In order for Astro to know what pages to generate at build time, we must provide a getStaticPaths() function. This function must return an array of objects containing the params property with any parameters that the route uses.

This particular page is located in apps/website/src/pages/blog/[slug].astro and will be available at the /blog/[slug] URL. Therefore, we need to return a slug parameter with a value matching what we want to be the URL segment for our blog posts. As shown in the previous section, I chose to use the blog post Markdown file path as the URL segment.

We can see it in action in the source code of the page:

---
import Layout from '../../layouts/BlogPostLayout.astro';
import { BlogPost } from '@leosvel/blog';

export function getStaticPaths() {
  const posts = Astro.fetchContent('../../data/blog-posts/*.md');

  return posts.map((post) => ({
    params: { slug: post.file.pathname.split('/').pop().split('.').shift() },
    props: { post },
  }));
}

const { Content, title, description, date, heroImage, heroImageAlt, thumbnailImage, thumbnailImageAlt } = Astro.props.post;
---

<Layout {title} {description} socialImage={thumbnailImage} socialImageAlt={thumbnailImageAlt}>
  <BlogPost {title} {date} {heroImage} {heroImageAlt}>
    <Content />
  </BlogPost>
</Layout>

As we can see above, I'm also using the Content property that is returned from the compiler when fetching Markdown files. It is a dynamically built component that contains the content of the Markdown file (the blog post in this case).

You might have noticed this page is using a different layout. It's a clone of the base layout with an extra stylesheet for the Prisma theme used by the code blocks in the blog posts. Due to an existing issue on Astro, it's currently not possible to compose it using slots.

The BlogPost component renders and styles the blog post. Since I don't have direct access to the generated markup for the blog post, I'm using global styles scoped to the .blog-content CSS class to ensure they are only applied to the blog post content.

// libs/blog/src/lib/BlogPost.astro
...
<article class="max-w-full sm:max-w-xl md:max-w-2xl lg:max-w-4xl mx-auto px-4 py-12 sm:px-8 md:px-12 text-sm sm:text-base text-cyan-900 leading-8 sm:leading-8 transition-all">
  ...
  <main class="blog-content">
    <slot />
  </main>
  ...
</article>

<style lang="scss" global>
  .blog-content {
    > * + * {
      @apply mt-4;
    }

    h2 {
      @apply mt-12 text-xl sm:text-2xl font-bold;
    }
    ...
  }
</style>

Improving the blog post page

With the blog post page in place, I wanted to make some improvements to it:

Add a link to the headings when hovering them.
Make external links to open in new tabs and add an icon to them to indicate that they are external.

But, I can't directly modify the HTML markup of the blog post page. It's generated by the Astro compiler when parsing the Markdown files. Fortunately, the Astro's out-of-the-box Markdown support is very powerful and extensible. It allows you to extend the default functionality by providing Remark and/or Rehype plugins.

So to achieve my goals, I configured the rehype-slug and rehype-autolink-headings plugins to generate links to the headings in the blog post. I also configured the rehype-external-links plugin to add the target="_blank" and rel="nofollow noopener noreferrer" attributes to external links, as well as adding an icon to them.

Below is the configuration in the apps/website/astro.config.mjs file to enable those plugins:

export default /** @type {import('astro').AstroUserConfig} */ ({
  ...
  markdownOptions: {
    render: [
      '@astrojs/markdown-remark',
      {
        rehypePlugins: [
          'rehype-slug',
          [
            'rehype-autolink-headings',
            {
              behavior: 'prepend',
              content: {
                type: 'element',
                tagName: 'span',
                properties: { className: ['heading-link'] },
                children: [
                  {
                    type: 'element',
                    tagName: 'img',
                    properties: { src: '/assets/link.svg' },
                    children: [],
                  },
                ],
              },
            },
          ],
          [
            'rehype-external-links',
            {
              content: {
                type: 'element',
                tagName: 'img',
                properties: {
                  src: '/assets/external-link.svg',
                  alt: 'External link icon',
                },
                children: [],
              },
              contentProperties: { className: ['external-link-icon'] },
            },
          ],
        ],
      },
    ],
  },
});

Final workspace structure

One of the benefits of using Nx is that you can easily visualize your workspace projects and their dependencies. By running the following command:

npx nx dep-graph

I got the following visualization of my website's projects:

Deploying to Cloudflare

Setting up automatic deployments to Cloudflare Pages from the GitHub repository was really easy. To do so, I did the following steps:

Accessed the Pages page in my Cloudflare dashboard
Clicked on the Create a project button
Added my GitHub account, selected the repository to deploy, and clicked on the Begin setup button:

Updated the build settings with:
- Project name: leosvel-dev
- Production branch: main
- Framework preset: None
- Build command: nx build website
- Build output directory: dist/apps/website
- Added the NODE_VERSION environment variable and set it to 16.13.2 so the build command runs with it

Clicked on the Save and deploy button

The build was immediately kicked off and the website was deployed to Cloudflare Pages in just a couple of minutes. By default, it was available on a subdomain of the pages.dev domain. To have it with my own domain, I had to set it up and I did it by following the steps below:

On the leosvel-dev project page, I clicked on the Custom domains tab
Clicked on the Set up a custom domain button
Entered my domain name and clicked on the Continue button
I was shown a confirmation page with the new DNS record for my domain and I clicked on the Activate domain button

That was it! The website was live and available on my domain.

Setting up Cloudflare Web Analytics

Cloudflare Web Analytics provides, in their own words, free, privacy-first analytics for your website. It allows you to track how your website is being used and how it is performing.

To enable it, I just had to add my website to it. This is done on the Web Analytics page of the Cloudflare dashboard. By default, Cloudflare injects the analytics script in the website pages, but since I wanted to use Partytown to move third-party scripts execution off of the main thread, I disabled the automatic setup.

I installed @builder.io/partytown:

yarn add -D @builder.io/partytown

Then, I added it to the Head component alongside the Cloudflare Web Analytics script with its type set to text/partytown. That type attribute with that value prevents browsers from executing the script and it provides a selector for Partytown to query for and do its magic.

Below is the code snippet for this:

// libs/common/src/lib/components/Head.astro
---
import { Partytown } from '@builder.io/partytown/react';
...
---
...
<!-- Partytown -->
<Partytown />

<!-- Cloudflare Web Analytics -->
<script type="text/partytown" defer src='https://static.cloudflareinsights.com/beacon.min.js' data-cf-beacon='{"token": "30e7f4a2b20548998ad672795c296f1c"}'></script>
...

One extra thing I needed to set up was to copy the required Partytown library files from the @builder.io/partytown package to the built application. This is necessary because those files are required to be served for Partytown to work correctly.

I made this change by renaming the existing build target in the website project configuration (apps/website/project.json) to build-astro and create a new target called build where I run the build-astro target and a small script I created to copy the relevant files:

{
  ...
  "targets": {
    "build-astro": {
      "outputs": ["dist/apps/website"],
      "executor": "@nxtensions/astro:build",
      "options": {}
    },
    "build": {
      "executor": "@nrwl/workspace:run-commands",
      "outputs": ["dist/apps/website"],
      "options": {
        "commands": [
          "nx run website:build-astro",
          "node ./tools/scripts/copy-partytown-files-to-dist.js"
        ],
        "parallel": false
      }
    },
    ...
  },
  ...
}

Performance

With everything in place and the website up and running, it was time to get some performance insights. Running Lighthouse on the live website for mobile gave me the following results:

Now, that's a good-looking report! Isn't it?

Final thoughts

Building my website was a really fun experience. I enjoyed the process and the fact that I took the chance to experiment with new technologies.

I'm really glad I chose Astro to build the website. Even though it still hasn't reached a stable release, it already works reasonably well and delivers on its promise of achieving great performance. The fact that it's not stable yet and still works this well excites me the more, it's only going to get better!

I achieved the goals I initially had in mind, creating a personal space where I can experiment with new technologies and blog about them and other topics.

It's this the end of the journey? Hell no!

This is just the beginning. I plan to add a couple more pages to the website, continue to improve its design, add more features to the blog, refactor some bits to clean up the code, and from time to time, I might rewrite or build multiple versions of it with different stacks (I'm looking at you Remix and Qwik).

Stay tuned! Happy coding!