Tailwind CSS is accelerating in popularity with its bold new approach to writing CSS for the web. You’re probably wondering how you can harness this new framework on a Siteglide site?
Tailwind’s approach to performance means it provides a huge range of utility classes, but to prevent it from slowing down your site with classes you don’t need, it builds a smaller CSS file containing just the subset of classes that you’re actually using in your project.
There are two main alternatives when it comes to generating an optimised Tailwind CSS file for your site:
Just In Time (JIT) Compilation in the Browser
A Command Line Interface (CLI) Compilation on your machine
That depends!
Both methods have their advantages, which we'll look at here, but it also depends on the preference of the developer and the type of project you're working on.
In the end, it depends on your preference.
If you use the Siteglide-CLI already to take advantage of modern code editing tools, you'll be right at home with Tailwind CLI. Using the Tailwind CLI with Siteglide
If you already work in the Siteglide Admin to keep everything in one place, you'll possibly find JIT compilation more convenient. Tailwind's JIT Compiler Via CDN
Question | Tailwind CLI | Tailwind JIT CDN |
---|---|---|
Will it support CSS classes that sit inside Secure Zones or other Liquid logical statements?
✔️
❌ See Safelisting classes which are added via user-interaction for possible workarounds and recommendations
Can I use the latest version of Tailwind?
✔️
Not yet. You can use most features from version 2.0 of Tailwind. We rely on Open Source code to provide the JIT method and it is not possible to keep it fully up to date as Tailwind brings out new versions.
Can I use 3rd party Tailwind Plugins?
✔️
✔️ See Beyond Code - Tailwind's JIT Tailwind Compiler Via CDN for details. The 1st party plugins will work well but we cannot guarantee that all 3rd party plugins will.
Can I regenerate the Tailwind from the Siteglide Admin without using the CLI
❌
✔️
Is it optimised for performance?
✔️ CSS is ready to go before user visits the page.
See the JIT section for more details on caching to optimise performance.
Beta - not recommended for Production
This is a Beta feature - not recommended for Production
Check Choosing a Build Method first to choose which option suits you best.
A quick way to use Tailwind from within the Siteglide Admin
With special thanks to the folks at Beyond Code, we’ve adapted their open-source Tailwinds JIT compiler via CDN to optimise it for the Siteglide Admin and the SiteBuilder libraries. We've also added caching for better performance. Later in this article, we may abbreviate the name of this tool to "the JIT Compiler" or simply "JIT".
Switch to JIT Mode in SiteBuilder Tailwind Settings
Enter the Module Admin and Scroll past the libraries to the Tailwind Settings Card and click the gear icon.
Then select “JIT”.
Create a Page Template
Create a Page Template for your Library using SiteBuilder and add it to the Pages you're working on in the Siteglide Admin.
And that's it; you're ready to start work! When your Page is loaded in the browser a new inline <style>
tag will be created including all the Tailwind classes your page needs.
Next, learn more about how the JIT compiler works by reading the rest of this article, including:
Where to theme and configure your Tailwind Build
Using caching to boost performance and how to update the cache when you make changes.
How to handle classes which show conditionally e.g. on user-interaction or after JavaScript events.
The JIT Compiler uses a version of the Tailwind Config file that lies within <script>
tags in the <head>
of the page, inside the Page Template. This is because the JIT method runs in the browser and wouldn't be able to access the standard tailwind-config.js
file on the root of a project.
You can edit the config file for the JIT method at the following default path in code editor: modules/module_86/layouts/tailwind/jit_tailwind_config_v4_0_0
. This path can be changed in the Page Template by adding the optional_path_to_jit_config
parameter to our Tailwind Liquid tag (using the platformOS format for partial paths)[https://documentation.platformos.com/developer-guide/pages/reusing-code-across-multiple-pages#step-2-include-the-partial]:
On page rendering, this will be inserted into a <script>
tag in the Page Template. For older versions of SiteBuilder the config could be edited directly in the Page Template.
By default, we set up the Tailwind config file the way the library you’re using recommends in its documentation.
Since the JIT Tailwind Compiler uses Tailwind version 2.0, you can use most of the configuration options from that version of Tailwind. See here: Tailwind CSS Version 2.0 Documentation
However, there are some exceptions, for example plugins which work a little differently. See the BeyondCode team’s blog for details: Beyond Code Blog - Tailwind's JIT Compiler Via CDN
Wait! My web pages are loading really slowly!
There’s another setting in the Tailwind Settings menu in SiteBuilder called Cache CSS.
Just In Time Tailwind Compilation is designed to be convenient for Developers. A developer adds new code to their site containing new Tailwind classes and those classes are instantly added to the CSS on the page. However, this convenience would normally come at a cost: the work being done by the JavaScript would slow the page down.
In production however, there is no need to rebuild the CSS on every page reload, we only need to do this after an update has been made.
Turning caching on in your Tailwind Settings menu turns on caching for Tailwind CSS across the site. The CSS is saved (base64 encoded) in your pages’ metadata once generated and when the page is loaded, the server will generate a <style>
tag based on that at the top of the document.
With caching on, the page will load lightning fast. Furthermore, since we optimise the CSS for that page only, it only needs to contain the clases on that page, rather than the entire site, so could even have speed advantages against an ordinary CLI Tailwind build.
If you add new Tailwind classes to a page, you can regenerate that page’s Tailwind by adding the query parameter ?tailwind=regenerate
at the end of the URL. (see URL Search Parameters for details).
After this, the page will load slowly for the developer once while this is calculated, but then the CSS against the page’s metadata will be updated and everyone else will experience the newly improved page at fast speeds.
What if my page shows different content depending on user-interaction, or depending on the user’s session? For example a button which either shows “login” or “logout” depending on the situation?
In this case, you may find that the content which changes is missing vital CSS because the Tailwind was only generated for the initial state the components were in.
Since the CDN runs after Liquid has rendered, this includes any classes which sit inside a Liquid if statement, as well as any JavaScript or XHR requests which might add classes to the DOM after initial page load.
One option is to add classes to the safelist in your Tailwind Congfig file: https://v2.tailwindcss.com/docs/optimizing-for-production#safelisting-specific-classes
Another possibility, if you find that your site has a lot of user-interaction and your safelist is getting quite long, might be that your site is better suited to a Using the Tailwind CLI with Siteglide instead!
Alternatively, you may wish to consider using the JIT mode for quick development now for convenience and then switching to a CLI build when the site goes live for reliability.
This article assumes you have completed the setup steps:
Having set up your local Project Folder with:
A Text Editor for viewing your Folder Structure inside a Project Folder
A Siteglide-CLI environment which connects your Project Folder to a Site
An npm script which runs a Tailwind compilation process
This article will delve a little deeper into the files you can modify to take full control of your Tailwind build!
We recommend if you are using VSCode that you download and enable this extension, which will help VSCode understand Tailwind's syntax and give you tips on things like colours: bradlc.vscode-tailwindcss
Also if you are using VS Code, this extension is useful for creating shortcuts to your favourite project folders: https://marketplace.visualstudio.com/items?itemName=alefragnani.project-manager
This tool is really helpful for fetching colours with all the shades you need generated for you: https://uicolors.app/create
(For Editing a Siteglide Site Which Uses a Tailwind Theme.)
Open up the Project Folder for your Site
In case your team have made any changes while you've been away, run siteglide-cli pull <env>
Split your terminal and simultaneously run:
siteglide-cli sync <env>
to push any code changes to the site
npm run tailwind
to watch for code changes and re-compile your Tailwind build (see #the-tailwind.min.css-file)
Make the necessary changes to your code.
src
is short for source. These files are not designed to be seen by the browser. Instead think of them as the recipe for a final Tailwind CSS file.
When you sync these files, they are still pushed to your Site because they are inside the marketplace_builder folder. This allows you to share changes with other users on the Site (or yourself on different machines).
tailwind.config.js
FileThis file is a configuration file and a Tailwind CSS feature which can be used to:
Create and modify Tailwind Variables e.g. Colour, Spacing
Include Plugins, for example we by default include the Flowbite plugin
You can learn all about Tailwind CSS configuration files here: https://tailwindcss.com/docs/configuration
You can find an example of default config variables here: https://github.com/tailwindlabs/tailwindcss/blob/master/stubs/config.full.js If you leave any variables blank, default values from this file will be used.
tailwind.css
FileThis file can be used to write ordinary CSS, or you can use Tailwind's documented features. The file should not be linked to on a website, instead it will be compiled into a new production-ready CSS file when you save it and run the npm run tailwind
build process.
Often with Tailwind CSS, you will find you will not need to enter this file often, as you can achieve most of the styling you want by using existing:
Utility Classes
Arbitrary Values in Utility Classes
Prefixes instead of Media Queries
However, if you do want to write your own CSS, you will not find yourself limited!
See here to understand how to insert your CSS into one of Tailwind's layers: https://tailwindcss.com/docs/adding-custom-styles#using-css-and-layer
See here to understand how to add custom classes which combine existing Tailwind utility classes: https://tailwindcss.com/docs/functions-and-directives#apply
tailwind.min.css
Final CSS FileSee the folder structure above to find this file. You should not need to create it or edit it manually. The npm run tailwind command will compile it automatically from the src files.
It should be linked in your Page Template, but by default a SiteBuilder Page Template will do this via a tailwind/head
Liquid include. You could optionally replace this with a <link> tag instead.
When you make changes to any of the following while npm run tailwind
is running in your terminal:
Your HTML (adding or removing new Tailwind classes)
Your JavaScript (adding or removing new Tailwind classes) (in case classes will be added via JavaScript, e.g. when a Flowbite Component changes state.
Your tailwind.config.js
file
Your tailwind.css
file
A new version of the tailwind.min.css
file will be generated. Use the Siteglide CLI to sync or deploy this to your Site to see your changes applied: Reference
Tailwind uses tree-shaking so that any classes which aren't used by the files referenced above will be removed from the final CSS file to make it as fast as possible. It will also be minified.