Version 0.2.0 released! Check out the release notes from GitHub Releases

Co-Locate .css.ts Source With .astro and .tsx Components — Compiled to Plain Stylesheets at Build Step

Using Salty CSS in .astro and .tsx Files

Create components

Salty CSS only picks up files whose names end with one of these suffixes:

SuffixWhen to use it
.css.tsDefault for any style or component file. Works everywhere.
.css.tsxSame as .css.ts, but JSX is allowed in the file.
.salty.tsAlias of .css.ts — pick whichever reads better in your project.
.styled.tsAlias of .css.ts, conventionally used for styled factories.
.styles.tsAlias of .css.ts, conventionally used for defineTemplates etc.

A .ts file with the same content but missing the right suffix will type-check fine but produce no CSS at build time — this is the single most common "my styles aren't appearing" cause. See Troubleshooting if you hit it.

Component structure

// /components/my-component.css.ts
import { styled } from "@salty-css/astro/styled";

export const Component = styled("div", {
  className: "wrapper", // Optional custom class name
  element: "section", // Optional override for the rendered HTML element
  base: {
    // Base styles that are always applied
    display: "flex",
    padding: "1rem",
    backgroundColor: "#f5f5f5",
  },
  variants: {
    // Conditional styles based on props
    size: {
      small: { padding: "0.5rem" },
      large: { padding: "2rem" },
    },
    color: {
      primary: { backgroundColor: "blue", color: "white" },
      secondary: { backgroundColor: "gray", color: "black" },
    },
  },
  compoundVariants: [
    // Styles applied when multiple variant conditions are met
    {
      size: "small",
      color: "primary",
      css: { borderRadius: "4px" },
    },
  ],
});

Using components

---
// src/pages/index.astro
import { Component } from "../components/my-component.css";
---

<Component size="small" color="primary">
  This is a Salty CSS component
</Component>

Naming components in DevTools

In development builds, every styled component renders with a data-component-name attribute matching its export name. Search for [data-component-name="Button"] in the elements panel to jump straight to it. You can override the label with the displayName option on the styled definition:

export const PrimaryButton = styled("button", {
  displayName: "PrimaryButton",
  base: {
    /* … */
  },
});

In production builds the attribute is stripped, so it's a debugging aid only.

Where to go next

Demo Projects