First and foremost, make sure to run pnpm install in the terminal in the root directory of this project. This will install all of the required dependencies and generate your node_modules folder. This step is very important.
This project uses Tailwind CSS, a utility-first CSS framework. The required dependencies should already be included in this project. If you are missing the node_modules folder, simply run pnpm install, and it should generate with the dependencies specified in the package.json file.
To enable Tailwind CSS Intellisense, you'll need the VS Code extension. I suggest installing the Tailwind CSS Extension Pack which comes with a few extensions that all work together to make using Tailwind CSS a much better experience. To learn more about it, click the link above.
In the root folder of the project, there is an assets/styles folder. This houses the tailwind.css file. This file is used to eventually generate the fully compiled Tailwind CSS styles. Once compiled, it outputs the classes to the styles.css file, also located in the assets/styles folder.
To work in a development environment, run the dev NPM script. To do so, use either method outlined below.
- Run
pnpm run devin the root folder of the project. - Use the NPM scripts shortcut in the bottom left corner of the File Explorer tab in VS Code.
This will start a long-running watch process that will generate your styles on-demand instead of generating everything in advance. This is extremely useful for making development quicker and more efficient. In the terminal, you should see the initial compile message and the amount of time it took. Anytime you save an HTML file, the tailwind.css file, or the tailwind.config.js file, the CSS will be processed and re-compiled. These styles will not be minified in the development process.
Please note that classes are added on-demand, but not removed on-demand. This is currently by design as stated by Adam Wathan, the creator of Tailwind CSS. To work around this (cache bust it), simply save the tailwind.css file. It will force a full re-compile and remove any unused classes.
To kill the watch process, put your focus in the terminal that the process is running it, and press CTRL + C. You should be prompted to confirm your termination of the process. Confirm your choice by entering Y followed by the ENTER key.
We will be using a VS Code extension to start our server up. Search for "Live Server" in the VS Code extensions tab. Alternatively, you can find it on the Visual Studio Marketplace.
Once you download and install the extension, you might see a new button in the lower right-hand corner of the window in the blue ribbon. It says Go Live. When you click that, it should start the server and open it on your browser.
If you do not see the button, simply right click on the index.html file in the VS Code file explorer, and click Open with Live Server.
Building for production is similar to building for development. Do either of the following to build the CSS for production.
- Run
pnpm run prodin the root folder of the project. - Execute
prodin the NPM scripts shortcut located at the bottom left of the File Explorer tab in VS Code.
Contrary to the development script we used before, this will not start a long-running watch process; rather, this script compiles the CSS once and only once. It will take only classes found in the HTML files located in the root folder and compile them into the styles.css file located in assets/styles/styles.css. These styles will be minified.
This project uses Gulp to build the project for deployment. By running Gulp, it will create a dist folder in the root of your project. Gulp will then copy over all the necessary files from your project's source and assets into the dist folder.
In addition to that, Gulp will also optimize and minify the files as needed. The HTML, SVG, and JavaScript files will all be minified. Minifying a file simply means removing whitespace and other unnecessary characters/symbols. We do this to reduce the size of the files(s).
The styles (css) will be copied over to the dist as well. Since the css is already minified by Tailwind CLI's use of PostCSS and the JIT Engine, we do not need to minify it here. It is important to first run pnpm run prod before running gulp. By not doing this, gulp will be using the non-minified version of your CSS.
The images will also be copied over as well and optimized using gulp-image, an image optimizer. This will only optimize PNG, JPG, and GIF images. Nearly every other image type will be copied over, but not optimized, including PDF files.
So how do you use Gulp? It's very easy! Here are three options. 1) Open the VS Code terminal and run the command gulp. This will execute the default task found in the gulpfile.js file in the root directory. The default task then executes, in order, all of the other tasks to build the project. 2) Alternatively, I have created an NPM script called gulp. You can run this from the bottom left corner of the VS Code window in the NPM Scripts tab. 3) If you do not see the NPM scripts tab, you may also run this command in the terminal by running pnpm run gulp, but at that point, just typing gulp is easier.
In the case that you need to change the name of the output folder from dist to something else, simply navigate to the gulpfile.js file and find the variable destination located near the top of the file. By default, it is set to dist, but you may change this by replacing the dist part of the string to whatever you'd like. Another common destination folder name is docs, which is used for deploying a project to GitHub Pages.
