--- title: Component Libraries description: Build reusable STX component libraries that work across projects with Stacks. --- # Component Libraries Build reusable STX component libraries that work across projects with Stacks. ## Hosted web components A `web-components` package can publish browser assets as part of `buddy build:web-components` or `buddy build:libs`: ```ts // config/library.ts, inside packages[] { name: '@acme/elements', kind: 'web-components', include: ['widgets/**'], hosted: { outputDir: 'public/widgets', base: '/widgets', entry: 'public/elements.js', }, } ``` The stable `/elements.js` entry re-exports a content-addressed revision under `/widgets/`. Its bundle is identical to the package's `dist/bundle.js`. Both an immutable manifest in the revision directory and `/widgets/manifest.json` record public file URLs, SHA-256, SHA-384 integrity, byte/gzip sizes and exact compiler style hashes for CSP. Existing revision files are never overwritten. An optional `hosted.loader` supplies an authored browser module with `source`, `exports` and `define`. For example, define a loader's module constant as `JSON.stringify('./bundle.js')` to import its sibling bundle. `hosted.styles` names project-relative literal `.css` text files for extra CSP hashes; the loader can import the same text with `with { type: 'text' }`. Keep application behavior in this loader; Stacks owns compilation, output identity, manifest generation and stable aliases. The [build skill](/skills/toolchain/build) documents the full contract and retained consumer/browser verification. ## Component Architecture ### File Structure Organize components by feature or complexity: ``` components/ ├── Button/ │ ├── Button.stx # Main component │ ├── Button.test.ts # Tests │ └── index.ts # Export ├── Modal/ │ ├── Modal.stx │ ├── ModalHeader.stx │ ├── ModalBody.stx │ ├── ModalFooter.stx │ └── index.ts ├── Form/ │ ├── Input.stx │ ├── Select.stx │ ├── Checkbox.stx │ └── index.ts └── index.ts # Main export ``` ### Single File Components Use STX SFCs with TypeScript: ```html ``` ## Props Design ### Type-Safe Props Always define prop types: ```typescript // Types can be exported for consumers export interface ButtonProps { variant?: 'primary' | 'secondary' | 'danger' | 'ghost' size?: 'sm' | 'md' | 'lg' disabled?: boolean loading?: boolean fullWidth?: boolean } const props = withDefaults(defineProps(), { variant: 'primary', size: 'md', disabled: false, loading: false, fullWidth: false, }) ``` ### Prop Validation Add runtime validation for complex props: ```html ``` ## Events ### Typed Events Define event types explicitly: ```html ``` ### v-model Support Support two-way binding: ```html ``` ## Slots ### Named Slots Provide flexibility with slots: ```html ``` ### Scoped Slots Pass data to slot content: ```html ``` ## Composables ### Extracting Logic Move reusable logic to composables: ```typescript // composables/useClickOutside.ts import { onMounted, onUnmounted, type Ref } from '@stacksjs/stx' export function useClickOutside( elementRef: Ref, callback: () => void ) { function handler(event: MouseEvent) { if (elementRef.value && !elementRef.value.contains(event.target as Node)) { callback() } } onMounted(() => { document.addEventListener('click', handler) }) onUnmounted(() => { document.removeEventListener('click', handler) }) } ``` ### Using in Components ```html ``` ## Styling ### CSS Variables Use CSS custom properties for theming: ```html ``` ### Tailwind Support Optionally support Tailwind: ```html ``` ## Accessibility ### ARIA Attributes Include proper accessibility: ```html ``` ### Keyboard Navigation Support keyboard users: ```html ``` ## Testing Components ### Unit Tests ```typescript // components/Button/Button.test.ts import { describe, it, expect } from 'bun:test' import { mount } from '@stacksjs/stx/testing' import Button from './Button.stx' describe('Button', () => { it('renders slot content', () => { const wrapper = mount(Button, { slots: { default: 'Click me' }, }) expect(wrapper.text()).toBe('Click me') }) it('applies variant class', () => { const wrapper = mount(Button, { props: { variant: 'danger' }, }) expect(wrapper.classes()).toContain('button--danger') }) it('is disabled when prop is set', () => { const wrapper = mount(Button, { props: { disabled: true }, }) expect(wrapper.attributes('disabled')).toBeDefined() }) it('shows loading spinner', () => { const wrapper = mount(Button, { props: { loading: true }, }) expect(wrapper.find('.spinner').exists()).toBe(true) }) }) ``` ## Best Practices 1. **Single responsibility** - Each component does one thing 2. **Consistent API** - Similar components have similar props 3. **Sensible defaults** - Work out of the box 4. **Type everything** - Full TypeScript coverage 5. **Document inline** - Use `` blocks 6. **Test thoroughly** - Unit tests for all features ## Related - [Getting Started](/guide/libraries/get-started) - Library setup - [Functions](/guide/libraries/functions) - Function libraries - [Publishing](/guide/libraries/publish) - Publishing workflow