solution • NodeJS — Initite a new project via npm packages ‐ SCSS or Tailwind stack - martindubenet/wed-dev-design GitHub Wiki

NOTE: The dollar signs $ mean a new command lines in your CLI Terminal.

$ cd ~/projects
$ mkdir project_folder
$ cd project_folder

This next command will launch the utility that will walk you through creating a package.json file. It only covers the most common items, and tries to guess sensible defaults.

$ npm init

1. package name : Leave default value
2. version : Leave default value
3. description : Describe this project
4. entry point : index.html
5. test command : Leave empty
6. git repository : Optional
7. keywords : Leave empty
8. author : My name
9. licence : Leave empty

Use this approach when you need a custom SCSS architecture with variables, mixins, and partials.

1. autoprefixer to add vendor prefixes where needed.
2. browser-sync to live-reload the browser on file changes.
3. clean-css-cli to create minified CSS versions.
4. sass (Dart Sass) to compile .scss files to .css.
5. postcss-cli to run autoprefixer via CLI.
6. stylelint to check the code for mistakes.

$ npm install <package_name> -D

Note: The trailing -D flag saves the package as a devDependency in package.json

$ npm install autoprefixer -D
$ npm install clean-css-cli -D
$ npm install sass -D
$ npm install postcss-cli -D
$ npm install stylelint stylelint-scss stylelint-order stylelint-config-standard-scss -D
$ npm install browser-sync concurrently

npm install sass clean-css-cli autoprefixer postcss-cli stylelint stylelint-scss stylelint-order stylelint-config-standard-scss -D && npm install browser-sync concurrently

This package will refresh only the part of the page affected by the latest compiled SCSS (CSS injection method), making the page reload faster.

"scripts": {
    "sass:watch": "sass --watch src/scss:dist/css --embed-sources",
    "sass:build": "sass src/scss:dist/css --style=compressed",
    "bs": "browser-sync start --proxy 'localhost:8080' --files 'dist/css/**/*.css, **/*.html'",
    "dev": "concurrently \"npm run sass:watch\" \"npm run bs\""
}

All those Style Lint Rules define what is allowed and what will throw an error. For example, "max-empty-lines": 2 will throw an error if you have more than 2 consecutive empty lines.

1. Create the config file: $ touch .stylelintrc.json
2. Paste the following minimal config:

{
  "extends": ["stylelint-config-standard-scss"],
  "rules": {
    "max-empty-lines": 2,
    "color-named": "never"
  }
}

PostCSS is required to run autoprefixer, which adds vendor prefixes automatically based on your browserslist.

Create the config file:

$ touch postcss.config.mjs

Paste this code:

export default {
  plugins: {
    autoprefixer: {},
  },
}

Add a browserslist array to your package.json to define which browsers to support:

"browserslist": [
  "last 2 major versions",
  ">= 1%",
  "Chrome >= 109",
  "Firefox >= 115",
  "Edge >= 109",
  "Safari >= 16",
  "iOS >= 16",
  "Android >= 109",
  "Opera >= 95",
  "not dead"
],

$ mkdir -p src/scss/layout
$ cd src/scss
$ touch main.scss _variables.scss _mixins.scss _layout.scss
$ cd layout
$ touch _header.scss _footer.scss

// MAIN ENTRY POINT
// Load all partials in order

@use 'variables' as *;
@use 'mixins' as *;
@use 'layout';
@use 'layout/header';
@use 'layout/footer';

Note: @use replaces the deprecated @import rule as of Dart Sass v1.23+. Variables and mixins imported with @use are namespaced by default (e.g. variables.$color).

Use this approach when you want utility-first CSS without writing custom SCSS. ⚠️ Tailwind CSS v4 is incompatible with Sass/SCSS preprocessors — choose one or the other.

$ npm install tailwindcss @tailwindcss/postcss postcss -D

Create the config file:

$ touch postcss.config.mjs

Paste this code:

export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
}

$ mkdir -p src/css
$ touch src/css/main.css

Add this single line at the top of src/css/main.css:

@import "tailwindcss";

That's it — no tailwind.config.js needed in v4. Tailwind detects your template files automatically.

All customizations are done directly in CSS using the @theme directive, right after the import:

@import "tailwindcss";

@theme {
  --font-sans: "Inter", sans-serif;
  --color-brand: oklch(0.55 0.22 260);
  --breakpoint-xs: 480px;
}

"scripts": {
  "dev": "postcss src/css/main.css -o dist/css/main.css --watch",
  "build": "NODE_ENV=production postcss src/css/main.css -o dist/css/main.css"
}

<head>
  <link rel="stylesheet" href="/dist/css/main.css">
</head>

Then start using Tailwind utility classes directly in your markup:

<h1 class="text-3xl font-bold text-brand underline">Hello world!</h1>