Using the Tailwind CLI with Siteglide

Before You Start

Check Choosing a Build Method first to choose which option suits you best.
Make sure you have already installed the Siteglide-CLI and are familiar with its use. This should give you the tools and the understanding you need to follow this guide. Introducing Siteglide CLI.

Introduction

Using the Command Line Interface (CLI) to build a Tailwind CSS file allows you to use the latest versions of TailwindCSS and its various 1st and 3rd party plugins.

If you prefer using the Siteglide CLI to build sites already, the two CLIs work very well together.

This guide is both a quick-start guide to get you started and a set of tips for how to build Tailwind CLI into your Siteglide workflow.

Quick Start

SiteBuilder Tailwind Settings

Navigate to the Settings tab in the SiteBuilder admin. (If this doesn't appear yet, you need to create a Page Template using a Tailwind Theme first.)

Then select "CLI".
Create Directory Structure

Open up a command-line terminal on your machine and change directory (cd) to your project folder. Use siteglide-cli pull <env> or siteglide-cli init to create your directory structure, if you haven't already.
Copy Files

Copy the files you need into your project folder, using whichever method you prefer.
- Copy package.json and package-lock.json from the example repository root to your own. (See troubleshooting if your project already has a package.json file.)
- Copy the tailwind.config.js and tailwind.css files from the example repository in this folder:
```
├───marketplace_builder
│   └───assets
│       └───modules
│           └───module_86
│               └───src
│                   tailwind.config.js
│                   tailwind.css
```
to an identical folder structure inside your own project. Using this custom location will allow it to be pushed and pulled to the site.

(If you prefer, you can create a new repository using the template in Github and then pull your site into the new folder!)
Install NPM Dependencies

In terminal, change directory to the root of your project folder
```
cd <my_folder_path>
```
and use the command
```
npm i
```
This will install the required dependencies needed to run the Tailwind CLI with our default setup.
Run the command siteglide-cli sync <env> to watch your marketplace_builder folder for changes and push these to the site.
Run the command: npm run tailwind to generate the CSS file for the first time. Since you started syncing in step 4, this will immediately be pushed to the site.
Set up your Page Template

You can either create a new template using SiteBuilder (option a) or edit an existing one (option b).

a. After you have synced your new css/tailwind.min.css file to the site, the SiteBuilder module will by default add this CSS file to any new templates created through the Module.

b. Edit your Page Template in Siteglide to change the default to your newly generated minified CSS file. If you've followed our example, this will be: <link rel="stylesheet" href="css/tailwind.min.css file">.

Changing the Page Template's default path to your compiled CSS

If you've edited your Tailwind CLI settings to create the min.css file in a different location, you can edit a Page Template generated through SiteBuilder so that it correctly links to the new file path. Add a new parameter optional_path_to_cli_css to the Tailwind Head file.

{% include 'modules/module_86/tailwind/head', optional_path_to_cli_css: 'css/tailwind2.min.css' %}

An Example Workflow using Siteglide CLI and Tailwind CLI

Each time you start work:

Pull the latest files from the site using siteglide-cli pull. It's important to have the latest files, because Tailwind only adds classes that you're actually using, but it can only see which files you're using if the files are available locally.
Use siteglide-cli sync to watch your marketplace_builder folder.
In terminal, run the command: npm run tailwind to watch for Tailwind changes.
Now you can begin work! Every time you make a change and save, your updated file will sync to Siteglide and so will a brand new version of the Tailwind CSS.

Adding Custom CSS

You can use the src file tailwind_src/tailwind.css to write any custom CSS for your Tailwind build. Check the Tailwind CSS documentation on Functions & Directives for details.

Troubleshooting

NodeJS and NPM Versions

If you see an error relating to the version of NPM, you may want to check which version of NodeJS and NPM you have installed on your machine:

node -v

npm -v

Follow the instructions here to update depending on your operating system: Installing NPM.

Version Control and Conflicts on Siteglide

If you work with other developers (or on multiple devices) on the same Siteglide project, it is definately recommended to use a version-control (otherwise known as source-control) tool like GitHub to share your package.json file etc. with the other developer.

The risk of conflicts is somewhat mitigated if you follow our reccomendation in the Quick Start guide of storing the tailwind.config.js file in a custom location (inside marketplace_builder/views/partials). This means it will be accessible via Siteglide CLI pull and editable via sync, but not from the Siteglide Admin.

If you are using version-control, the node_modules folder can become very large and we recommend adding this to your .gitignore file or equivalent.

I've got a `syntax error` when I run the `npm run tailwind` command

There might be an issue with your Tailwind Config File. Try temporarily reverting the file to the state it is in here and see if that fixes the problem. If not contact Sitegurus.

I've got a different problem

Please contact Sitegurus.

Removing JIT Code from the Template

If you are certain that you won't be using the Tailwind's JIT Compiler Via CDN in the future, you can optionally remove the <script type="module"> and <script type="tailwind-config"> tags containing the JIT version of the Tailwind Config file from the Page Template. This may help avoid clutter and confusion.

Alternative Configurations

I already have a package JSON file.

In that case, use npm to add dev-dependencies to the existing file rather than copying across our file:

npm i -D tailwindcss@3.1.5

npm i -D flowbite@1.4.7

npm i -D flowbite-typography@1.0.2

Adding Dependencies to a package.json file.

I use an alternative package manager, instead of NPM.

This is fine! We don't cover this in our example, but there is plenty of documentation out there. You can use the information in the answer above to see which dependencies we use.

Editing this configuration

This repository is a "quick-start" guide, not fixed instructions for how to use Tailwind with Siteglide. Feel free to read the relevant documentation from Tailwind, NPM, Flowbite and configure Tailwind however you wish.

I prefer to work in the Siteglide Admin

Have you tried our JIT Compiler? Based on the fantastic JIT Compiler from the folks at Beyond Code, we've added caching to allow better production speeds and integrated it with a Siteglide Template. This allows a developer to use Tailwind entirely from the Siteglide Admin without using any CLI tools.