# Svelte Gym
**Rapidly create, exercise, and share Svelte component states via URL-encoded permalinks.**
## Why Svelte Gym?
Developing and testing components should be seamless. Svelte Gym provides a playground environment to exercise your components and ensure they respond correctly to various inputs and constraints.
**Key Features:**
- **URL-Driven State:** Every control and property is reflected in the URL. Share a link, share a state.
- **Visual Regression Ready:** Deterministic URLs make it easy to use tools like [BackstopJS](https://github.com/garris/BackstopJS) to detect visual regressions.
- **LLM Friendly:** The URL structure provides a context-rich, text-based representation of your component's state, making it ideal for AI-assisted development and debugging.
### Use Cases
- **Responsive Testing:** How does the component respond when the parent element resizes?
- **Style Verification:** Is the font size on the parent element respected?
- **Edge Cases:** Does text overflow expectedly? Is bad data (null, NaN, undefined) handled gracefully?
- **Collaboration:** Share a specific component state with a colleague or an LLM to reproduce a bug.
## Getting Started
### Installation
```bash
npm install -D svelte-gym
# or
pnpm install -D svelte-gym
# or
bun install -D svelte-gym
```
### Svelte 4 Support
Svelte Gym is written in Svelte 5. If you are still using Svelte 4, you can import the Svelte 4-compatible versions of the components from the `/v4` subpath:
```svelte
```
### Basic Usage (Svelte 5)
Create a `+page.svelte` route for your component (e.g., `src/routes/gym/my-component/+page.svelte`):
```svelte
{#snippet componentToTest()}
{/snippet}
{#snippet controls()}
{/snippet}
```
## AI / LLM Workflow & Best Practices
Svelte Gym is designed to be "interpreter-friendly." To ensure the best results and visual parity when using LLMs for component development:
### 1. Minimal `componentToTest` Snippet
The `componentToTest` snippet should **only** contain the component being tested.
> [!IMPORTANT]
> **Avoid wrapping the component in extra `div` or `section` tags.** This ensures that the component's layout and styles are tested in isolation, matching how it will appear when deployed.
**Correct:**
```svelte
{#snippet componentToTest()}
{/snippet}
```
**Incorrect:**
```svelte
{#snippet componentToTest()}
```
### 2. Use `Gym*` Input Components
Always use the built-in `Gym` prefixed input components (e.g., `GymSlider`, `GymTextbox`, `GymCheckbox`) in the `controls` snippet.
> [!IMPORTANT]
> **Do not use standard HTML inputs or other custom components.** `Gym*` inputs are specifically designed to handle and test edge cases like `null`, `undefined`, `NaN`, and `Infinity`, which are critical for robust component testing and are not supported by standard inputs.
### 3. URL-Driven State & Reproductions
1. **Describe the Issue:** "My component breaks when the label is too long."
2. **Generate a Reproduction:** The LLM can generate a Svelte Gym URL with a long label string encoded in the parameters.
- _Example:_ `http://localhost:5173/gym/button?label=Super+Long+Label+That+Breaks+Layout`
3. **Fix and Verify:** You can verify the fix visually, and the URL serves as a regression test case.
## API Reference
### `TestHarness`
The main wrapper for your component playground.
**Props:**
- `maxWidth` (number, optional): Maximum width constraint for the test area.
- `maxHeight` (number, optional): Maximum height constraint for the test area.
- `maxFontSize` (number, optional): Maximum font size for the test area.
**Snippets:**
- `componentToTest`: Place the component you want to test here.
- `controls`: Place `Gym*` controls here to modify `props`.
### `restoreProps(props)`
Synchronizes the URL search parameters with your local `props` object. This must be called in your component's `
```
In your controls:
```svelte
```
## Support
## ESLint Plugin
Svelte Gym ships with an ESLint plugin (`eslint-plugin-svelte-gym`) to help catch common test harness setup mistakes at lint time.
### Installation
```bash
# The plugin is included in the svelte-gym package
npm install -D eslint-plugin-svelte-gym
```
Or reference it locally if using the source:
```json
{
"devDependencies": {
"eslint-plugin-svelte-gym": "file:./eslint-plugin"
}
}
```
### ESLint Configuration
Add to your `.eslintrc.cjs`:
```js
module.exports = {
overrides: [
{
files: ['*.svelte'],
plugins: ['svelte-gym'],
rules: {
'svelte-gym/require-restore-props': 'warn',
'svelte-gym/no-duplicate-prop-names': 'warn',
'svelte-gym/require-props-state': 'error',
'svelte-gym/single-component-in-test': 'error'
}
}
]
};
```
### Rules
#### `svelte-gym/require-restore-props` ⚠️
Warns when a file imports `TestHarness` but never calls `restoreProps()`. Without this call, URL parameters won't be restored into component state.
**Correct:**
```svelte
```
**Incorrect:**
```svelte
```
#### `svelte-gym/no-duplicate-prop-names` ⚠️
Warns when multiple `Gym*` components use the same `name` prop. Duplicate names cause permalink parameter collisions.
**Incorrect:**
```svelte
```
#### `svelte-gym/require-props-state` ❌
Errors when `restoreProps(props)` is called but `props` was not declared with `$state()`. Without `$state()`, restored values won't trigger Svelte reactivity.
**Correct:**
```svelte
```
**Incorrect:**
```svelte
```
#### `svelte-gym/single-component-in-test` ❌
Errors when the `componentToTest` snippet contains more than one element, or when its single element is a plain HTML element (not a component). This prevents wrapper `` or `
` tags that make things look correct in the harness but behave differently in production.
**Correct:**
```svelte
{#snippet componentToTest()}
{/snippet}
```
**Incorrect:**
```svelte
{#snippet componentToTest()}
{/snippet}
```
## Known Issues
- **Type definitions generated as `Record`:** If your published package emits broken `.d.ts` files where all component props are typed as `Record`, ensure your `peerDependencies.svelte` is set to `"^5.0.0"` (not `">=3.0.0"`). The `@sveltejs/package` type generator uses this field to select the correct type shims — a range that intersects with Svelte 3 causes it to use legacy shims that don't understand `$props()`. See [sveltejs/kit#12972](https://github.com/sveltejs/kit/issues/12972) for details.
## License
MIT