0
# Storybook Addon Controls
1

2
The `@storybook/addon-controls` package is a deprecated migration helper for Storybook 9.0+. It does not provide any functional API - instead, it throws an error when imported to guide users through the Storybook 9.0 migration process. The controls functionality has been consolidated into other Storybook packages as part of the package structure changes.
3

4
## Package Information
5

6
- **Package Name**: @storybook/addon-controls
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @storybook/addon-controls` (not recommended)
10
- **Status**: Deprecated - Migration helper only
11

12
## Core Imports
13

14
All import patterns result in the same migration error being thrown:
15

16
```typescript
17
import '@storybook/addon-controls';
18
```
19

20
CommonJS:
21

22
```javascript
23
const controls = require('@storybook/addon-controls');
24
```
25

26
Import from specific entry points:
27

28
```typescript
29
import '@storybook/addon-controls/preview';
30
import '@storybook/addon-controls/manager';
31
import '@storybook/addon-controls/register';
32
```
33

34
## Basic Usage
35

36
**This package intentionally has no functional usage.** All imports immediately throw an error to guide migration:
37

38
```typescript
39
// This will throw an error
40
import '@storybook/addon-controls';
41

42
// Error thrown:
43
// "Your Storybook project is referring to package @storybook/addon-controls, 
44
// which no longer exists in Storybook 9.0 and above. Please refer to the 
45
// Storybook 9 migration guide for instructions on how to fix this issue: 
46
// https://storybook.js.org/docs/9/migration-guide#package-structure-changes"
47
```
48

49
## Architecture
50

51
This package uses a simple error-throwing architecture:
52

53
- **Error Module**: Single `error.ts` file containing the migration error message
54
- **Entry Points**: All entry points (`index.ts`, `preview.tsx`, `manager.tsx`) import and execute the error module
55
- **Build Process**: The package builds to distribution files that preserve the error-throwing behavior
56
- **Zero Dependencies**: No runtime dependencies - pure error throwing functionality
57

58
## Capabilities
59

60
### Migration Error Handling
61

62
The sole capability of this package is to throw a descriptive error that guides users to the migration documentation.
63

64
```typescript { .api }
65
/**
66
 * All entry points import this error module which immediately throws
67
 * a migration error with guidance to the Storybook 9 migration guide
68
 */
69
declare const migrationError: never;
70
```
71

72
**Error Details:**
73
- **Error Type**: `Error`
74
- **Error Message**: "Your Storybook project is referring to package @storybook/addon-controls, which no longer exists in Storybook 9.0 and above. Please refer to the Storybook 9 migration guide for instructions on how to fix this issue: https://storybook.js.org/docs/9/migration-guide#package-structure-changes"
75
- **Migration Guide**: https://storybook.js.org/docs/9/migration-guide#package-structure-changes
76

77
## Migration Information
78

79
### Package Structure Changes
80

81
In Storybook 9.0+, the controls functionality has been consolidated into other packages. Users must:
82

83
1. **Remove** references to `@storybook/addon-controls` from their configuration
84
2. **Follow** the Storybook 9 migration guide to update their setup
85
3. **Use** the new package structure for controls functionality
86

87
### Replacement
88

89
The controls functionality is now built into the core Storybook experience and does not require a separate addon package. Refer to the official Storybook documentation for current controls usage patterns.
90

91
## Entry Points
92

93
All package entry points defined in `package.json` lead to the same error-throwing behavior:
94

95
```typescript { .api }
96
// Main entry (.)
97
declare module '@storybook/addon-controls' {
98
  // Immediately throws migration error
99
}
100

101
// Preview entry (./preview)  
102
declare module '@storybook/addon-controls/preview' {
103
  // Immediately throws migration error
104
}
105

106
// Manager entry (./manager and ./register)
107
declare module '@storybook/addon-controls/manager' {
108
  // Immediately throws migration error
109
}
110

111
declare module '@storybook/addon-controls/register' {
112
  // Immediately throws migration error  
113
}
114
```
115

116
## Error Handling
117

118
Since this package only throws errors, there is no error handling beyond the migration error itself. Users encountering this error should follow the migration guide rather than attempting to catch or handle the error.