0
# @storybook/addon-backgrounds
1

2
@storybook/addon-backgrounds is a **deprecated** Storybook addon package as of version 9.0. This package serves as a compatibility layer that throws informative error messages directing users to migrate to Storybook's new package structure. The actual backgrounds functionality has been moved to Storybook's core blocks system.
3

4
## Package Information
5

6
- **Package Name**: @storybook/addon-backgrounds
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @storybook/addon-backgrounds` (not recommended)
10
- **Status**: Deprecated in Storybook 9.0
11
- **Migration Guide**: https://storybook.js.org/docs/9/migration-guide#package-structure-changes
12

13
## Core Imports
14

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

17
```typescript
18
import * as backgrounds from '@storybook/addon-backgrounds';              // Throws error
19
```
20

21
```typescript
22
import * as preview from '@storybook/addon-backgrounds/preview';          // Throws error
23
```
24

25
```typescript  
26
import * as manager from '@storybook/addon-backgrounds/manager';          // Throws error
27
```
28

29
CommonJS:
30

31
```javascript
32
const backgrounds = require('@storybook/addon-backgrounds');      // Throws error
33
const preview = require('@storybook/addon-backgrounds/preview');  // Throws error
34
const manager = require('@storybook/addon-backgrounds/manager');  // Throws error
35
```
36

37
## Basic Usage
38

39
**This package cannot be used functionally.** Any attempt to import or require this package will result in an error:
40

41
```typescript
42
import '@storybook/addon-backgrounds'; 
43
// Throws: "Your Storybook project is referring to package @storybook/addon-backgrounds, 
44
// which no longer exists in Storybook 9.0 and above. Please refer to the Storybook 9 
45
// 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
The package implements a simple error-throwing mechanism designed to provide clear migration guidance:
52

53
- **Error Module** (`src/error.ts`): Contains a single throw statement that executes immediately when imported
54
- **Entry Point Strategy**: All entry points (`index.ts`, `preview.tsx`, `manager.tsx`) simply import the error module
55
- **Immediate Execution**: The error is thrown at module import time, preventing any further code execution
56
- **Consistent Behavior**: All entry points exhibit identical error behavior to ensure consistent user experience
57

58
This design ensures that any attempt to use the deprecated package results in clear, actionable error messages directing users to the migration guide.
59

60
## Capabilities
61

62
### Error Throwing
63

64
The sole capability of this package is to throw migration errors when imported.
65

66
```typescript { .api }
67
/**
68
 * Error thrown when attempting to import any entry point of this package
69
 * Contains migration guidance for users upgrading to Storybook 9.0+
70
 */
71
Error: "Your Storybook project is referring to package @storybook/addon-backgrounds, 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"
72
```
73

74
### Entry Points
75

76
All entry points exhibit identical behavior:
77

78
```typescript { .api }
79
// Main entry point
80
import '@storybook/addon-backgrounds';                    // Throws Error
81

82
// Preview entry point  
83
import '@storybook/addon-backgrounds/preview';            // Throws Error
84

85
// Manager entry points
86
import '@storybook/addon-backgrounds/manager';            // Throws Error
87
import '@storybook/addon-backgrounds/register';           // Throws Error (alias)
88
```
89

90
## Migration Information
91

92
### Background Functionality Location
93

94
The backgrounds functionality previously provided by this addon has been moved to:
95

96
- **Storybook's core blocks system** as part of the package structure changes in version 9.0
97
- Users should remove this dependency and configure backgrounds through the new core system
98
- See the official Storybook 9 migration guide for detailed instructions
99

100
### Recommended Actions
101

102
1. Remove `@storybook/addon-backgrounds` from dependencies
103
2. Update Storybook configuration to use the new core blocks system
104
3. Follow the migration guide at: https://storybook.js.org/docs/9/migration-guide#package-structure-changes
105

106
## Error Handling
107

108
This package intentionally throws errors for all operations. There is no way to suppress or handle these errors - they are designed to be fatal to ensure users are aware of the deprecation and migration requirements.
109

110
```typescript { .api }
111
/**
112
 * Internal error throwing mechanism - executes immediately when imported
113
 * Located in src/error.ts - not a function but a top-level throw statement
114
 */
115
throw new Error("Your Storybook project is referring to package @storybook/addon-backgrounds, 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");
116
```
117

118
## Package Structure
119

120
The package contains the following entry points, all of which import the error throwing mechanism:
121

122
- `src/index.ts` - Main entry point
123
- `src/preview.tsx` - Preview entry point  
124
- `src/manager.tsx` - Manager entry point
125
- `src/error.ts` - Core error throwing functionality
126

127
All source files contain only `import './error';` statements.