FSCSS tutorial for FSCSS tutorial

Posted on Apr 20

Using st-core.fscss with React & Next.js

#webperf #react #nextjs #fscss

React and Next.js can't parse .fscss syntax natively — so the workflow is: write FSCSS → compile to CSS → import as normal. This keeps your charts at zero runtime JavaScript while still fitting into any component tree.

1. Install the FSCSS CLI

npm install -g fscss

2. Create Your Stylesheet

Create a .fscss file anywhere in your project — src/styles/Chart.fscss is a good home.

/* Chart.fscss */
@import((*) from st-core);

@st-chart-line(.chart-line)
@st-chart-fill(.chart-fill)

.my-chart {
  @st-chart-points(10, 20, 16, 15, 66, 50, 80, 54)
}

Full mixin reference: github.com/fscss-ttr/st-core.fscss

3. Compile to CSS

fscss src/styles/Chart.fscss src/styles/Chart.css

This outputs a standard .css file — no bundler plugins needed.

4. Import Into Your Component

import "./styles/Chart.css";

export default function DashboardChart() {
  const dataStyles = {
    "--st-p1": "30%",
    "--st-p2": "65%",
    "--st-p3": "45%",
  };

  return (
    <div className="my-chart" style={dataStyles}>
      {/* Chart rendered via CSS clip-path — zero JS overhead */}
    </div>
  );
}

CSS custom properties are your data bridge. React state writes the values; st-core renders the chart.

5. Normalizing Data Points

@st-chart-points() uses human-friendly values (e.g. 0–100), but the underlying clip-path percentages are inverted — 0% is the top of the container and 100% is the bottom. Use this helper to convert your raw data before passing it to CSS:

/**
 * Normalizes a raw data value into a CSS custom property string
 * for use with st-core.fscss chart mixins.
 *
 * @param {number} value     - Raw data point (e.g. 0–100)
 * @param {number} [min=0]   - Dataset minimum
 * @param {number} [max=100] - Dataset maximum
 * @returns {string}         - e.g. "35%"
 */
function normalizePoint(value, min = 0, max = 100) {
  const clamped = Math.max(min, Math.min(max, value));
  const normalized = 100 - ((clamped - min) / (max - min)) * 100;
  return `${normalized.toFixed(2)}%`;
}

// Example: map an array of values to CSS custom properties
const data = [10, 42, 78, 55, 67, 60, 91, 82];
const dataStyles = Object.fromEntries(
  data.map((v, i) => [`--st-p${i + 1}`, normalizePoint(v)])
);

Pass dataStyles directly to your chart div and your data will scale correctly regardless of dataset range.

Key Considerations for Next.js

Global styles — Import compiled CSS in app/layout.tsx (App Router) or pages/_app.tsx (Pages Router) for shared dashboard tokens:

// app/layout.tsx
import "../styles/Chart.css";

CSS Modules — st-core works best with global selectors since chart class names are set at compile time. If you need scoping, output to Chart.module.css and reference classes via the module object.

Zero Runtime — Compiled output is plain CSS. No JS chart library ships to the client, which means faster TTI and no hydration concerns.

Re-compiling — Add the compile step to your package.json scripts so it runs before dev/build:

"scripts": {
  "predev": "fscss src/styles/Chart.fscss src/styles/Chart.css",
  "prebuild": "fscss src/styles/Chart.fscss src/styles/Chart.css"
}

That's it — FSCSS charts in React with a single compile step and no runtime cost.

Resource https://github.com/fscss-ttr/st-core.fscss

DEV Community