carbon-svelte

Carbon-svelte is a component library based on IBM's Carbon design system. Specifically, carbon-svelte is a customized version of Carbon Components Svelte and uses Tailwind, Svelte, and previously developed tools—such as svelte-forms—to provide a custom look, feel, and functionality for Texas State University applications.

Documentation

For full documentation and information about individual component usage and best practices, visit component-library.app.qual.txst.edu. Alternatively, you can clone this repository and run the SvelteKit application locally, see Developing.

Installation

The quickest way to get started with carbon-svelte is to use one of our fullstack app templates, such as the GraphQL App Template.

Component catalog

This package ships a Vite plugin that catalogs which library components your app uses on which routes, derived from the module graph during the production build. It helps you (and us) evaluate whether a library release affects your app without auditing the changelog by hand.

To enable it, add one line to your app's vite.config.ts:

import { sveltekit } from '@sveltejs/kit/vite'
import { componentCatalog } from '@txstate-mws/carbon-svelte/vite'
import { defineConfig } from 'vite'

export default defineConfig({
	plugins: [sveltekit(), componentCatalog()]
})

The next vite build will emit two assets into the client build output, served at the root of your deployed app (respecting Vite's base):

• component-catalog.json — machine-readable: for each +page/+layout/+error route, the components it imports from each tracked library (imports that were tree-shaken out of the route's bundle are flagged in a treeShaken field), plus installed library versions, a list of all routes, and a composition map recording which components each library component uses internally (so transitive impact can be computed).
• component-catalog.html — a human-readable viewer for the JSON with by-route and by-component views, text filtering, and toggleable display of transitive component usage and tree-shaken imports (hidden by default).

The plugin is build-only; it does nothing during vite dev, and the assets only exist in production builds.

Options

All options are optional:

| Option | Default | Description | | --- | --- | --- | | libraries | ['@txstate-mws/carbon-svelte', 'carbon-components-svelte'] | Package names to track. Vite aliases like $lib also work. | | fileName | 'component-catalog.json' | Name of the emitted JSON asset. The viewer is emitted next to it with an .html extension. | | routesDir | 'src/routes' | SvelteKit routes directory, relative to the Vite root. | | ubiquitous | ['Toasts'] | App-wide singleton components rendered by wrapper components as a matter of course. The viewer shows them transitively on layout entries only (where they are genuinely rendered) instead of on every page. Direct imports are always cataloged. | | viewer | true | Set false to emit the JSON only, without the HTML viewer. |

Developing

Once you've cloned the project and installed dependencies with npm install, start a development server:

npm run dev

Everything inside src/lib is part of the library, everything inside src/routes is used for documentation.

Day-to-day work happens on the dev server. The exception is the component catalog, which only exists in production builds — to try it locally, run docker-compose up --build, which serves a full build at http://localhost (and also runs the Playwright test suite once on the way up).