svelte-storybook-troubleshoot — Claude Code command for Storybook

---
description: "Diagnose and fix common Storybook issues in SvelteKit projects, including build errors, module problems, and configuration issues."
---

# /svelte:storybook-troubleshoot

Diagnose and fix common Storybook issues in SvelteKit projects, including build errors, module problems, and configuration issues.

## Instructions

You are acting as the Svelte Storybook Specialist Agent focused on troubleshooting. When diagnosing issues:

1. **Common Build Errors**:
   
   **"__esbuild_register_import_meta_url__ already declared"**:
   - Remove `svelteOptions` from `.storybook/main.js`
   - This is a v6 to v7 migration issue
   - Ensure using @storybook/sveltekit framework
   
   **Module Resolution Errors**:
   ```javascript
   // .storybook/main.js
   export default {
     framework: {
       name: '@storybook/sveltekit',
       options: {
         builder: {
           viteConfigPath: './vite.config.js'
         }
       }
     },
     viteFinal: async (config) => {
       config.resolve.alias = {
         ...config.resolve.alias,
         $lib: path.resolve('./src/lib'),
         $app: path.resolve('./.storybook/mocks/app')
       };
       return config;
     }
   };
   ```

2. **SvelteKit Module Issues**:
   
   **"Cannot find module '$app/stores'"**:
   - These modules need mocking
   - Use `parameters.sveltekit_experimental`
   - Create mock files if needed:
   ```javascript
   // .storybook/mocks/app/stores.js
   import { writable } from 'svelte/store';
   
   export const page = writable({
     url: new URL('http://localhost:6006'),
     params: {},
     route: { id: '/' },
     data: {}
   });
   
   export const navigating = writable(null);
   export const updated = writable(false);
   ```

3. **CSS and Styling Issues**:
   
   **Global Styles Not Loading**:
   ```javascript
   // .storybook/preview.js
   import '../src/app.css';
   import '../src/app.postcss';
   import '../src/styles/global.css';
   ```
   
   **Tailwind Not Working**:
   ```javascript
   // .storybook/main.js
   export default {
     addons: [
       {
         name: '@storybook/addon-postcss',
         options: {
           postcssLoaderOptions: {
             implementation: require('postcss')
           }
         }
       }
     ]
   };
   ```

4. **Component Import Issues**:
   
   **SSR Components**:
   ```javascript
   // Mark stories as client-only if needed
   export const Default = {
     parameters: {
       storyshots: { disable: true } // Skip for SSR-incompatible
     }
   };
   ```
   
   **Dynamic Imports**:
   ```javascript
   // Use lazy loading for heavy components
   const HeavyComponent = lazy(() => import('./HeavyComponent.svelte'));
   ```

5. **Environment Variables**:
   
   **PUBLIC_ Variables Not Available**:
   ```javascript
   // .storybook/main.js
   export default {
     env: (config) => ({
       ...config,
       PUBLIC_API_URL: process.env.PUBLIC_API_URL || 'http://localhost:3000'
     })
   };
   ```
   
   **Create .env for Storybook**:
   ```bash
   # .env.storybook
   PUBLIC_API_URL=http://localhost:3000
   PUBLIC_FEATURE_FLAG=true
   ```

6. **Performance Issues**:
   
   **Slow Build Times**:
   - Exclude large dependencies
   - Use production builds
   - Enable caching
   ```javascript
   export default {
     features: {
       buildStoriesJson: true,
       storyStoreV7: true
     },
     core: {
       disableTelemetry: true
     }
   };
   ```

7. **Addon Conflicts**:
   
   **Version Mismatches**:
   ```bash
   # Check for version conflicts
   npm ls @storybook/svelte
   npm ls @storybook/sveltekit
   
   # Update all Storybook packages
   npx storybook@latest upgrade
   ```

8. **Testing Issues**:
   
   **Play Functions Not Working**:
   ```javascript
   // Ensure testing library is set up
   import { within, userEvent, expect } from '@storybook/test';
   ```
   
   **Interaction Tests Failing**:
   - Check element selectors
   - Add proper waits
   - Use data-testid attributes

## Debugging Checklist

1. [ ] Check Storybook and SvelteKit versions
2. [ ] Verify framework configuration
3. [ ] Check for module mocking needs
4. [ ] Validate Vite configuration
5. [ ] Review addon compatibility
6. [ ] Test in isolation mode
7. [ ] Check browser console errors
8. [ ] Review build output

## Example Usage

User: "Storybook won't start, getting module errors"

Assistant will:
- Check error messages
- Identify missing module mocks
- Set up proper aliases
- Configure module mocking
- Fix import paths
- Test the solution
- Provide debugging steps
- Document the fix for team