🚀 Auto-Compile FSCSS to CSS with GitHub Actions + GitHub Pages

When working with FSCSS, it’s useful to have your styles compiled automatically whenever you push changes. In this guide, we’ll set up a workflow that:

• Compiles .fscss → .css automatically
• Commits the compiled CSS
• Deploys a demo page with GitHub Pages

The result is a simple CI/CD pipeline for your styles.

You can see the complete example repository here:

👉 https://github.com/fscss-ttr/clipfscss

Live demo:

👉 https://fscss-ttr.github.io/clipfscss/demo

---

1. Project Structure

Here’s the structure used in the example project.

repo/
│
├── .github/workflows
│   ├── compile.yml
│   └── pages.yml
│
├── src/
│   └── style.fscss
│
├── dist/
│   └── f.css
│
├── demo/
│   └── index.html
│
├── package.json
└── package-lock.json

Explanation

• "src/" → FSCSS source files
• "dist/" → compiled CSS output
• "demo/" → static example page
• ".github/workflows/" → automation scripts

---

1. Install FSCSS

Install via npm.

npm install -g fscss

Your package.json should look like this:

{
  "dependencies": {
    "fscss": "^1.1.17"
  },
  "scripts": {
    "build:css": "fscss src/style.fscss dist/f.css"
  }
}

Now you can compile locally:

npm run build:css

---

1. Setup GitHub Action

Create:

.github/workflows/compile.yml

name: Compile FSCSS

on:
  push:
    paths:
      - "**.fscss"

permissions:
  contents: write

jobs:
  build-css:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repo
        uses: actions/checkout@v4
        with:
          persist-credentials: true

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 22

      - name: Install dependencies
        run: npm install

      - name: Compile FSCSS
        run: npm run build:css

      - name: Commit compiled CSS
        run: |
          git config user.name "github-actions"
          git config user.email "[e-mail]"
          git add dist/f.css
          git commit -m "Auto compile FSCSS" || echo "No changes"
          git push

What happens here?

push .fscss
↓
GitHub Action runs
↓
FSCSS compiles
↓
dist/f.css updated
↓
CSS committed automatically

---

1. Deploy the Demo with GitHub Pages

Create another workflow:

.github/workflows/pages.yml

name: Deploy static site

on:
  push:
    branches: ["main"]

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  deploy:
    runs-on: ubuntu-latest

    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    steps:
      - uses: actions/checkout@v4

      - uses: actions/configure-pages@v5

      - uses: actions/upload-pages-artifact@v3
        with:
          path: .

      - id: deployment
        uses: actions/deploy-pages@v4

Now every push will automatically update your GitHub Pages site.

---

1. Using the CSS

Example HTML:

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

Your demo page will load the compiled CSS generated by the workflow.

---

Why This Setup Is Useful

This setup provides:

✔ automatic FSCSS compilation
✔ CI/CD integration
✔ clean project structure
✔ automatic demo deployment

It’s a simple but powerful workflow for projects using FSCSS.

---

Full Example Repository

If you'd like to see everything working together, check out the example

Repository:
https://github.com/fscss-ttr/clipfscss