@@ -49,7 +49,7 @@ npm run storybook
49
49
## Development Setup
50
50
51
51
1 . ** Requirements** :
52
- - Node.js >= 18 .0.0
52
+ - Node.js >= 20 .0.0
53
53
- npm (not yarn - the project uses npm workspaces)
54
54
2 . ** Ports** :
55
55
- Jupyter server: 8686
@@ -100,7 +100,7 @@ Components showcased in `storybook/`
100
100
- Single quotes, trailing commas (all)
101
101
- 80 character line width
102
102
- LF line endings
103
- - Ignores ` attic/ ` folder
103
+ - Ignores ` attic/ ` folder and ` *.mdx ` files (to prevent MDX comment corruption)
104
104
105
105
### Pre-commit Hooks
106
106
@@ -113,9 +113,12 @@ Components showcased in `storybook/`
113
113
- ` lerna.json ` - Monorepo configuration
114
114
- ` eslint.config.js ` - ESLint flat config
115
115
- ` .prettierrc.json ` - Prettier configuration
116
+ - ` .prettierignore ` - Prettier exclusions (includes MDX files)
117
+ - ` .nvmrc ` - Node version specification
116
118
- ` dev/config/jupyter_server_config.py ` - Server settings
117
119
- ` packages/react/src/jupyter/JupyterContext.tsx ` - Core context provider
118
120
- ` packages/react/src/state/JupyterReactState.ts ` - Zustand store
121
+ - ` patches/ ` - Third-party module patches (applied via patch-package)
119
122
120
123
## CI/CD
121
124
@@ -141,6 +144,8 @@ Components showcased in `storybook/`
141
144
- Updated ESLint to v9 flat config format
142
145
- Removed deprecated ` .eslintignore ` in favor of ignores in config
143
146
- Added ` --quiet ` flag to lint command (show errors only)
147
+ - Updated Node.js requirement from 18 to 20+
148
+ - Added .nvmrc file for Node version management
144
149
145
150
### Code Quality Fixes
146
151
@@ -152,6 +157,19 @@ Components showcased in `storybook/`
152
157
- Replaced ` Function ` types with proper signatures
153
158
- Added security attributes to external links (` rel="noreferrer" ` )
154
159
160
+ ### Storybook MDX Fixes
161
+
162
+ - Fixed malformed MDX comments from ` {/_ ` to ` {/** `
163
+ - Updated all 13 MDX story files to use proper JSX comment syntax
164
+ - Added MDX files to .prettierignore to prevent comment corruption
165
+
166
+ ### Build & CI Improvements
167
+
168
+ - Fixed webpack source map warnings by excluding problematic packages
169
+ - Created patch for @jupyterlite/javascript-kernel-extension missing logo files
170
+ - Updated GitHub Actions workflows to use Node 20
171
+ - Added patch-package for third-party module fixes
172
+
155
173
## Troubleshooting
156
174
157
175
### Common Issues
@@ -168,6 +186,15 @@ Components showcased in `storybook/`
168
186
- Ensure Jupyter server is running on port 8686
169
187
- Check token in server config
170
188
189
+ 4 . ** Storybook build errors**
190
+ - Check MDX comment syntax (must be ` {/** **/} ` )
191
+ - Verify patches are applied: ` npx patch-package `
192
+ - Missing logo files error fixed by @jupyterlite patch
193
+
194
+ 5 . ** Node version issues**
195
+ - Use Node 20+ (check with ` node --version ` )
196
+ - Use .nvmrc file: ` nvm use `
197
+
171
198
## Notes for AI Assistants
172
199
173
200
- The ` attic/ ` folder contains archived/experimental code - do not modify
0 commit comments