Beginner tutorial for setting up tailwind v 4 using the standalone CLI (no node.js)

[verachell]

I felt there was a need for a beginner tutorial for those getting started with the tailwind v 4 standalone CLI (no node.js, no npm). Particularly for those who had the v 3 standalone CLI working fine, the v 4 has quite a few differences. Most of the official documentation for v 4 refers to the node.js versions, not the standalone.

I pieced this together from various GH discussions, issues and the official documentation when trying to set up the Tailwind 4 standalone CLI with one of my projects. I wanted to put the info together all in one place in case it helps others, particularly beginners who just want an easy step by step guide.

The good news is that it's super-easy - it's actually easier to use Tailwind v 4 than v 3 with the standalone CLI.

This tutorial was done with Tailwind release v 4.0.0 in a Linux environment.

1. Download the tailwind binary

Go to the latest release of tailwind on GitHub at https://github.com/tailwindlabs/tailwindcss/releases/ and find the appropriate one for you operating system. Then download it - here's an example with the Linux version

curl -sLO https://github.com/tailwindlabs/tailwindcss/releases/download/v4.0.0/tailwindcss-linux-x64

you will see the name of the tailwind executable in your working directory. It will be called something like tailwindcss-linux-x64

Give it execute permissions

chmod u+x tailwindcss-linux-x64

Then change the name to tailwindcss for convenience

mv tailwindcss-linux-x64 tailwindcss

2. Tell Tailwind where your source files are

The biggest difference here from v 3 is that there is no init step. In fact, if you try to use the init command you will get an error.

You also won't need a tailwind.config.js file for a standard simple setup - UNLESS as @standingwave helpfully pointed out in the comment below #15855 (comment) , you are using plugins and/or you can't easily specify in one line the directory where the source files are to be watched, and/or you need to specify file types that tailwind otherwise wouldn't look at, THEN you should use a tailwind.config.js file. If this is you, see that comment link thread for more information on how to do that. It will be more likely to apply if you're upgrading from 3 to 4, but may still apply for certain 4.0.0 setups.

Instead, you need an input file with a minimum of 1 line. I call it in.css but you can call it anything you like. In that file, put this line (but read on if your website files are not in the same directory):

in.css:

@import "tailwindcss";

BUT - this does not tell Tailwind where your source files are. If you do not specify, Tailwind will assume by default that the root of your source files is the same as your current Tailwind working directory. Therefore, if your website files do not have the same root directory as your Tailwind working directory, you will need to specify to Tailwind where to look.

You do this by modifying that line in the in.css file to specify the root directory of your source files. In the example shown below, the root of my source files was 2 levels above my Tailwind working directory. Adjust your path as appropriate.

in.css:

@import "tailwindcss" source("../..");

For an alternative way to indicate sources, take a look at the comment below by @arashThr at #15855 (comment)

3. Have Tailwind generate your css file

Then get Tailwind to generate the css file for your project, specifying your desired input file and output files. e.g.

./tailwindcss --input in.css --output out.css

In this example, Tailwind generates the out.css which is the css file to use in your website.

You can now use the Tailwind CSS classes in your project.

If you're making changes on the fly, you may prefer to use the --watch option e.g. ./tailwindcss --input in.css --output out.css --watch This means you don't have to run the ./tailwindcss command every time you change your css classes

Optional: additional info (ignore this for straightforward situations)

• Are you using plugins? Take a look at the info in the comment below at Beginner tutorial for setting up tailwind v 4 using the standalone CLI (no node.js) #15855 (reply in thread)
• Do you wish to disable base styles on preflight? See a couple of different approaches in the discussion below at Beginner tutorial for setting up tailwind v 4 using the standalone CLI (no node.js) #15855 (comment)

[saent-x]

What if the source is from npm root? How do we configure...

[verachell]

Gosh, sorry, your use case may be a bit more advanced than I or my tutorial can handle. My tutorial is for systems with no npm anywhere on it. I have tested it out on a DigitalOcean Ubuntu droplet without npm or node.js installed, and it works. But I don't know how to handle the situation if you had npm before (and therefore npm-related sources) but want to migrate to the standalone CLI without npm/node.js on your system. Is the situation you are describing?

I am not covering any type of 3 -> 4 migration here in the tutorial (because I have not had to do it so I don't know how). This is just how to set up 4.0.0 from scratch on a system without npm/node.js and how that differed from Tailwind v 3 without npm/node.js.

I'm sorry I can't help with your use case, I wish I could! And let me know if I have misunderstood something.

Would someone else please be willing to help with this question?

[saent-x]

Thanks for the response @verachell

I am trying to see if it's possible to not have to use node_modules folder...

In my previous configuration with v3 I didn't need the node_modules folder and only have to run npx tailwindcss ...

But as it is I think I have to either install the node_modules for v4 because of the @import 'tailwindcss'

[sanyam-dev]

./tailwindcss --input in.css --output out.css --watch

out.css shows errors

[verachell]

Hmm. Upon further testing, I agree it seems there are some issues with certain situations. Unfortunately I'm not sure what the cause is or how to fix it. After reading your comment, I tried both the linux-x64 and linux-x64-musl release on my local Linux machine and I couldn't get Tailwind to run at all there (core dumped), even though it was working fine on the DigitalOcean Ubuntu droplet which I originally was using to make this tutorial.

I also tried the linux-arm64 release on a Raspberry Pi just now according to the tutorial instructions and it worked fine - it ran and the html page was styled correctly.

Can you tell me more about what errors you are seeing? Do you mean the resultant out.css stylesheet contains errors, or are you getting errors even just running tailwind? Will it run at all, for example what happens if you do ./tailwindcss -h

These issues may be beyond me or the scope of my tutorial, but I would like to help figure out what is going on. It's at least clear that there is some platform dependency going on since I can't get it to run on my local linux x64 machine, yet the exact same binary works fine on a DigitalOcean droplet. The arm-64 version on a local Raspberry Pi works fine.

[arashThr]

Thanks for the post.
Another option that worked for me was to change the working directory with --cwd option when running the command line.
With that, I no longer needed to add source("../")

[verachell]

Thank you for alerting me to this, very helpful thanks, I wasn't aware of this earlier. I have updated the original post to reference your comment.

It was interesting to try it out. As you mentioned, --cwd option specifies an override to the current working directory (rather than only the sources specifically) and as such is very powerful. Therefore, if using --cwd, people should be aware that tailwindcss then expects to find the input css file (e.g. the in.css) and the sources (website files) in the directory specified by --cwd . It will write out.css to that same directory.

This helpfully allows you to keep the tailwind binary executable in an entirely different location to your website files, the input css and the output css.

While using the --cwd override option, you are still able to override the sources further on top of that if desired e.g. via source("... in the input css file, in case that is helpful. So you can use them together. At least, that worked when I tested it on my local Raspberry Pi machine. I personally found it was easiest to keep on top of everything mentally if using just --cwd or sources as opposed to both together. But it's nice to know they can be put together if needed for the use case.

[KorigamiK]

this still has an issue for me. i'm wrapping the tailwindcss cli in my app and if i use the --cwd option for the sources with html files ignored in my git project the tailwind classes don't seem to be generated. there doesn't seem to be any option to disable git support or look for specified files either.

can this be fixed or am i missing something?

[verachell]

I did some looking around. The docs say sources which are in your .gitignore file will be ignored by tailwindcss and this is expected behavior for Tailwind https://tailwindcss.com/docs/detecting-classes-in-source-files#explicitly-registering-sources Which was news to me! It's not at all intuitive.

Anyway (if I understood your problem correctly?) there is a workaround: the docs say that you can put a line in your in.css file to explicitly make it look at sources which would normally be ignored because they are in your .gitignore file for example like this:
@source "../this-source-is-in-my-gitignore";

The source is supposed to be expressed relative to your stylesheet, which admittedly becomes confusing when used with --cwd - I think they need to document that more clearly.

I hope this helps your problem and that I didn't misunderstand anything. Please let me know if your problem still persists with this workaround (things are a bit busy right now and I don't have time to test it myself, I'm sorry). Additionally, in terms of things to keep an eye on, I noticed a recently-raised known issue with the .gitignore in the regular node/npm version of Tailwindcss generally, see #16669 - but it may not have any bearing on what you mentioned.

[standingwave]

This was super helpful, thanks for taking the time to share the info. One change I would make is that you should still go ahead and create your own tailwind.config.js and ensure that the CLI knows where to find it.

The CLI still uses the config file and if you want to add plugins or if say the files you want the CLI to watch are in a non-standard place or non-standard file types you may end up in a world of hurt until you figure it out.

[verachell]

Wow, this is very valuable information thanks, I had no idea this was possible until you mentioned it. I have updated the original post accordingly to reference your comment.

A bit of additional info for beginners on how to do this if this situation applies to you - the info is from the official docs at https://tailwindcss.com/docs/upgrade-guide#using-a-javascript-config-file - in full disclosure I haven't tested out this particular feature. Here's what to do:

Tailwind v 4 doesn't automatically check for a tailwind.config.js file so if you're in that situation, you'll need to specify this with its location in your input css file e.g.

@config "../../tailwind.config.js";

For info on your tailwind.config.js file and how to format it, see the v3 docs at https://v3.tailwindcss.com/docs/installation

Remember, most standard basic 4.0.0 setups won't need this, it's for if you're using plugins, have non-standard file types that Tailwind otherwise wouldn't look it, or if you can't specify a single root directory of where the website source files are

[rstmsn]

Thanks for taking the time to put this document together. The official documentation for standalone CLI users appears to be lacking, at this time.

I have following your instructions, however I'm encountering the following issue:

input.css:
@config "./tailwind.config.js"; @import "tailwindcss"; .....

When running tailwindcss -i input.css -o output.css, the following error occurs:

Error: Can't resolve 'tailwindcss' in '/Documents/Code/assets/css'

Do you have any thoughts on whats happening here?

It appears that the import directive is causing the standalone cli to look for a 'tailwindcss' package, in the css directory, but obviously, it isn't there.
Correct me if I'm wrong but shouldn't the contents of this package be bundled with the standalone-cli ? As opposed to being something that's included with the project source files?

Kind regards

[rstmsn]

Please note this issue appears to have been corrected in the latest release (4.0.3).

[verachell]

Oh good! Thank you for looking into this and updating. This problem still replicated for me in 4.0.3 though. I will look into it again when I have more time.

[arashThr]

4.0.4 is released. It fixed the issue I had running the build locally with Docker.

[verachell]

Thank you for the update. I confirm that the setup you described also works for me now in 4.0.6 on my local Raspberry Pi (linux-arm64). I agree it looks like they fixed the issue

[ct5845]

Thanks for the guide, migrating from v3, using a config which pulls in

  plugins: [
    require("@tailwindcss/typography"),
    require("@tailwindcss/container-queries"),
   ]

it works perfectly locally when running on windows, but fails when building with tailwindcss-linux-x64 on docker... don't get any error information other then "exited with code 1" annoyingly, so hard to work out what's going on!

My in.css has been simplified to just load the config;

@config "./tailwind.config.js";
@import "tailwindcss";

I've tried only importing one of the plugins, both fail individually too. If i remove both... build succeeds!

Anyone have any ideas? / using plugins with the standalone cli in v4, on a linux build?

[verachell]

Hello, thank you for your comment. I looked into plugins with the standalone CLI to see what was going on. I am glad you brought this up because I had not done anything with plugins until now. OK, it looks like we don't put the plugins in the config file anymore. In the docs for version 4 at https://tailwindcss.com/docs/functions-and-directives#plugin-directive it says that to use a plugin we need to place it in the input css file like this:

@plugin "@tailwindcss/typography";

On my (admittedly very simple) local test, it worked when I took plugin references out of the config file and put plugins in the in.css file formatted as in the line above. It's clearer if I show each of my files below. I confirm that this worked for me with the typography plugin and provided the expected typography - this was for the linux-arm64 executable on raspberry pi. I didn't test the other plugin as I am unfamiliar with its visual effects.

tailwind.config.js:

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ['../*.html'],
  theme: {
	extend: {},
  },
  plugins: [],
}

in.css:

@config "./tailwind.config.js";
@import "tailwindcss";
@plugin "@tailwindcss/typography";

Hopefully this should solve your problem. If not, let me know

[ct5845]

star thank you.

Unfortunately @tailwindcss/container-queries causes the build still to error that way, but just @tailwindcss/typography seems to work just fine as you tested. I'll have to dig a bit deeper and perhaps raise an issue over there. Still thank you, progress!

[verachell]

I looked into the container-queries plugin just now. I think I may have found the problem. I agree that if using it the same way as typography in the in.css, I wind up with an error message Error: Can't resolve '@tailwindcss/container-queries' in '/home...

However: It appears they may have built in container-queries (or at least some of its functionality) into the tailwindcss core. I tested a container-query example, the one they list on the plugin site (files shown below), and it worked - WITHOUT specifying the plugin anywhere. Therefore, see if your container queries work when you leave off any references to the plugin.

Here are more details of my test files. It is a very simple test case using the tailwindcss-linux-arm64 executable v 4.0.6 on a Raspberry Pi.

in.css:

@config "./tailwind.config.js";
@import "tailwindcss";
@plugin "@tailwindcss/typography";

tailwind.config.js:

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ['../*.html'],
  theme: {
	extend: {},
  },
  plugins: [],
}

The relevant section of my test.html file:

...
<div class="@container">
  <div class="@lg:underline">
    This text will be underlined when the container is larger than `32rem`
  </div>
</div>
...

The resultant html file appears in the browser as expected, with that text section underlined if the container is large and becomes not underlined when I narrow down the window.

I'm puzzled by the inconsistent approach they made - why treat the typography plugin differently to container-queries?

It is additionally possible that only some (but not all) of container-queries functionality has made it into the tailwindcss core - I haven't done further testing beyond the example they gave in the container-queries plugin.

I didn't notice any documentation about the different approach for different plugins. It would have been helpful if they had documented this more clearly, or if it is documented somewhere it would help if it was made to be easier to find.

[muriloime]

Thanks a lot for this @verachell

[AshwinSundar]

This is the only documentation out there that explains how to configure the Standalone CLI for Tailwind v4. Thank you so much. @tailwindlabs can you guys please update your documentation and properly support Standalone CLI? There are a lot of us outside the npm ecosystem that would love to use Tailwind without having to rely on npm in our project.

[Pezzab]

Hello, thank you for the tutorial. One thing I struggle with is uninstalling the @base component.

The old way of adding tailwindcss meant this was straightforward:

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

Becomes:

/* @tailwind base ; */
@tailwind components;
@tailwind utilities;

Now there is only one instruction to add to my input.css this is now somewhat opaque:

@config "./../../tailwind.config.js";
@import "tailwindcss";

I've found some documentation that says this can be done in tailwind.config.js but so far I can't seem to get this to have any effect:

module.exports = {
  corePlugins: {
    preflight: false,
    }...

Other elements in the config are otherwise working.

There are two reasons why I'd like to be able to easily remove base styles - debugging, and for projects like for example WordPress theming when I'd like to use Tailwind for a child theme without double loading all the preflight styles included in the parent theme.

[Pezzab]

So it turns out if I comment out tailwindcss in input.css but leave in tailwind.config.js I can still add custom styles and utilities there and use them in my child theme style.css which works well enough for me:

@config "./../../tailwind.config.js";
/* @import "tailwindcss"; */

[verachell]

Thank you for writing in. I believe there is a solution that is built into v 4.x, however, I have only tested it on my very simple test usage case. So I'm not sure if it will work on your more complex real world situation. If there are still problems please let me know. Here is the info you need:

In https://tailwindcss.com/docs/preflight#disabling-preflight it looks like disabling preflight works the same for standalone as it does for the npm version. So what you need to do is, in your in.css file, instead of doing @import "tailwindcss" source(".."); do this instead. It's all in in.css, you won't need to put it in tailwind.config.js . Note that my html test file is only 1 directory up, for your 2 levels above, you will need to do source("../..") in the below example:

in.css:

@layer theme, base, components, utilities;
@import "tailwindcss/theme.css" layer(theme) source("..");
@import "tailwindcss/utilities.css" layer(utilities) source("..");

The reason behind this is that when we write @import "tailwindcss"; it really does this:

@layer theme, base, components, utilities;
@import "tailwindcss/theme.css" layer(theme);
@import "tailwindcss/preflight.css" layer(base);
@import "tailwindcss/utilities.css" layer(utilities);

And they say to remove the base preflight styles, we can just omit the @import "tailwindcss/preflight.css" layer(base); I added the source info on the end of the lines, I'm not sure if that was the optimal place to put it or not - if anyone knows, please write in! When I tested it on my test file (shown below) it worked.

test.html:

<head>
<link rel="stylesheet" href="inner/out.css">
</head>
<body>
<h1>Tailwind test</h1>
<p>The test of tailwind - want to disable base styles</p>
<button class="bg-blue-500 ">Button A</button>
<button class="bg-cyan-500 ">Button B</button>
<button class="bg-pink-500 ">Button C</button>
</body>

In the test, my h1 became big again because preflight base styles were disabled. I was still seeing background colors for the buttons.

The test was done using the Tailwind v 4.0.7 binary tailwindcss-linux-x64 on Linux Mint.

[Pezzab]

Thank you, I'll give it a shot.

[Pezzab]

That works like a charm, thanks again!

[LokeshwarPrasad3]

In the latest Tailwind installation for Vite+React , the command npx tailwindcss init doesn't work, meaning the tailwind.config.js file isn't generated. How can we configure and extend properties like custom classes for colors, font families, screen breakpoints, etc.?
I commonly rely on such configurations to enhance project styling.

[verachell]

Hello, in v 4 of Tailwind, theme info goes in the in.css file and not in tailwind.config.js - for more info on adding your own custom styles see docs at https://tailwindcss.com/docs/adding-custom-styles I have not tested out anything with themes though. Alternatively, with the standalone CLI, you are able to still use tailwind.config.js if you want to, but you will have to tell Tailwind about it - see a previous comment at #15855 (reply in thread)

I hope this helps! This tutorial does not cover Vite+React or npm/npx/Node.js so I'm not sure if the above information will help your more complex use case.

[FlaviusRaducu]

Thank you for the guide @verachell.

For people that are running Alpine Linux (or any other Linux with musl), make sure you download the musl binary; otherwise, your binary will not work.