storybook addon next
v1.8.0
Cet addon a été obsolète en faveur de @ storybook / nextjs qui est l'addon officiel de contes pour soutenir les fonctionnalités de Next.js dans le livre de contes. Il soutient tout ce que storybook-addon-next fait et bien plus encore! J'ai même travaillé à développer cela avec eux, donc vous devriez être entre de bonnes mains.
Consultez les documents de migration pour plus de détails sur la façon de migrer.
? Pas de prise en charge de configuration pour next.js : fatigué d'écrire et de déboguer la configuration de webpack? What Next.js prend en charge les sentiers battus, cet addon rend possible dans le livre de contes
Composant d'image de next.js (support partiel)
Routage suivant.js
Sass / SCSS
Modules CSS / SASS / SCSS
Styled JSX
Postcss
Importations absolues
Configuration d'exécution
Configuration de webpack personnalisée
Manuscrit
.js et non l'extension .mjs (ie next.config.js pas next.config.mjs )Pour exécuter n'importe quel exemple, construisez d'abord l'addon en exécutant
yarn buildà la racine de ce dépôt.
Installer storybook-addon-next à l'aide yarn :
yarn add --dev storybook-addon-next Ou npm :
npm install --save-dev storybook-addon-next // .storybook/main.js
module . exports = {
// other config ommited for brevity
addons : [
// ...
'storybook-addon-next'
// ...
]
}?? C'est ça! Les fonctionnalités prises en charge devraient fonctionner hors de la boîte.
Voir la documentation pour plus de détails sur le fonctionnement des fonctionnalités prises en charge dans cet addon.
Si quelque chose ne fonctionne pas comme vous vous en doutez, n'hésitez pas à ouvrir un problème.
Cet addon peut être transmis un objet Options pour la configuration addionale si nécessaire.
Par exemple:
// .storybook/main.js
const path = require ( 'path' )
module . exports = {
// other config ommited for brevity
addons : [
// ...
{
name : 'storybook-addon-next' ,
options : {
nextConfigPath : path . resolve ( __dirname , '../next.config.js' )
}
}
// ...
]
}nextConfigPath : le chemin absolu vers le next.config.js Suivant / L'image est notoirement difficile à travailler avec le livre de contes. Cet addon vous permet d'utiliser le composant Image de next.js sans configuration!
Étant donné que le composant d'image dispose de fonctionnalités, comme l'optimisation de l'image, configurée par des options qui nécessitent le fichier de configuration suivant.js à lire et à traiter par le cadre et qu'il n'y a pas de fonction publique exposée par next.js à résoudre et ces options, il n'est pas possible de prendre en charge ces fonctionnalités stable.
Si vous voulez voir cela mieux soutenu, n'hésitez pas à contribuer à la discussion du côté de Next.js ou de la discussion de notre côté
Les images locales fonctionnent très bien avec cet addon! Gardez à l'esprit que cette fonctionnalité n'a été ajoutée que dans Next.js v11.
import Image from 'next/image'
import profilePic from '../public/me.png'
function Home ( ) {
return (
< >
< h1 > My Homepage </ h1 >
< Image
src = { profilePic }
alt = "Picture of the author"
// width={500} automatically provided
// height={500} automatically provided
// blurDataURL="../public/me.png" set to equal the image itself (for this addon)
// placeholder="blur" // Optional blur-up while loading
/>
< p > Welcome to my homepage! </ p >
</ >
)
} Les images distantes fonctionnent également très bien!
import Image from 'next/image'
export default function Home ( ) {
return (
< >
< h1 > My Homepage </ h1 >
< Image
src = "/me.png"
alt = "Picture of the author"
width = { 500 }
height = { 500 }
/>
< p > Welcome to my homepage! </ p >
</ >
)
} Toutes Image Next.js sont automatiquement non optimisées pour vous.
Si placeholder = "blur" est utilisé, le blurdataurl utilisé est le SRC de l'image (désactivant ainsi efficacement l'espace réservé).
Voir ce problème pour plus de discussions sur la façon dont Image Next.js sont gérées pour le livre de contes.
Ce format n'est pas encore pris en charge par cet addon. N'hésitez pas à ouvrir un problème si c'est quelque chose que vous voulez voir.
Cette solution est fortement basée sur le livre de contes-Addon-next-Router, donc un grand merci à lifeiscontent pour avoir fourni une bonne solution dont cet addon pourrait fonctionner.
Le routeur de Next.js est automatiquement coupé pour vous de sorte que lorsque le routeur est interagi, toutes ses interactions sont automatiquement enregistrées dans l'onglet Actions du livre de contes si vous avez l'addon d'actions.
Les remplacements par histoire peuvent être effectués en ajoutant une propriété nextRouter sur les paramètres de l'histoire. L'addon fusionnera superficiellement tout ce que vous mettez ici dans le routeur.
import SomeComponentThatUsesTheRouter from "./SomeComponentThatUsesTheRouter" ;
export default {
title : "My Story" ,
} ;
// if you have the actions addon
// you can click the links and see the route change events there
export const Example = ( ) => < SomeComponentThatUsesTheRouter /> ;
Example . parameters : {
nextRouter : {
path : "/profile/[id]" ,
asPath : "/profile/ryanclementshax" ,
query : {
id : "ryanclementshax"
}
}
}Voir cet exemple pour une référence.
Les valeurs par défaut globales peuvent être définies dans Preview.js et seront fusionnées avec le routeur par défaut.
export const parameters = {
nextRouter : {
path : '/some-default-path' ,
asPath : '/some-default-path' ,
query : { }
}
}Voir cet exemple pour une référence.
Les valeurs par défaut sur le routeur Stubbed sont les suivantes (voir Globals pour plus de détails sur le fonctionnement des Globals)
const defaultRouter = {
locale : context ?. globals ?. locale ,
route : '/' ,
pathname : '/' ,
query : { } ,
asPath : '/' ,
push ( ... args : unknown [ ] ) {
action ( 'nextRouter.push' ) ( ... args )
return Promise . resolve ( true )
} ,
replace ( ... args : unknown [ ] ) {
action ( 'nextRouter.replace' ) ( ... args )
return Promise . resolve ( true )
} ,
reload ( ... args : unknown [ ] ) {
action ( 'nextRouter.reload' ) ( ... args )
} ,
back ( ... args : unknown [ ] ) {
action ( 'nextRouter.back' ) ( ... args )
} ,
prefetch ( ... args : unknown [ ] ) {
action ( 'nextRouter.prefetch' ) ( ... args )
return Promise . resolve ( )
} ,
beforePopState ( ... args : unknown [ ] ) {
action ( 'nextRouter.beforePopState' ) ( ... args )
} ,
events : {
on ( ... args : unknown [ ] ) {
action ( 'nextRouter.events.on' ) ( ... args )
} ,
off ( ... args : unknown [ ] ) {
action ( 'nextRouter.events.off' ) ( ... args )
} ,
emit ( ... args : unknown [ ] ) {
action ( 'nextRouter.events.emit' ) ( ... args )
}
} ,
isFallback : false
} Si vous remplacez une fonction, vous perdez l'intégration de l'onglet Action Automatique et devez le créer vous-même.
export const parameters = {
nextRouter : {
push ( ) {
// we lose the default implementation that logs the action into the action tab
}
}
} Faire vous-même ressemble à quelque chose comme ça (assurez-vous d'installer le package @storybook/addon-actions ):
import { action } from '@storybook/addon-actions'
export const parameters = {
nextRouter : {
push ( ... args ) {
// custom logic can go here
// this logs to the actions tab
action ( 'nextRouter.push' ) ( ... args )
// return whatever you want here
return Promise . resolve ( true )
}
}
}Les feuilles de styles Global SASS / SCSS sont également prises en charge sans aucune configuration supplémentaire. Importez-les simplement dans Aperçu.js
import '../styles/globals.scss' Cela inclura automatiquement l'une de vos configurations SASS personnalisées dans votre fichier next.config.js .
À l'heure actuelle, seule l'extension
.jsde la configuration suivant.js est prise en charge, pas.mjs. Voir suivante.config.js pour plus de détails.
const path = require ( 'path' )
module . exports = {
// any options here are included in sass compilation for your stories
sassOptions : {
includePaths : [ path . join ( __dirname , 'styles' ) ]
}
}Next.js prend en charge les modules CSS hors de la boîte, donc cet addon le prend également en charge.
// this import works just fine in Storybook now
import styles from './Button.module.css'
// sass/scss is also supported
// import styles from './Button.module.scss'
// import styles from './Button.module.sass'
export function Button ( ) {
return (
< button type = "button" className = { styles . error } >
Destroy
</ button >
)
}La solution CSS dans JS intégrée pour next.js est stylée-jsx, et cet addon prend également en charge cela hors de la boîte, zéro config.
// This works just fine in Storybook with this addon
function HelloWorld ( ) {
return (
< div >
Hello world
< p > scoped! </ p >
< style jsx > { `
p {
color: blue;
}
div {
background: red;
}
@media (max-width: 600px) {
div {
background: blue;
}
}
` } </ style >
< style global jsx > { `
body {
background: black;
}
` } </ style >
</ div >
)
}
export default HelloWorldVous pouvez également utiliser votre propre configuration Babel. Ceci est un exemple de la façon dont vous pouvez personnaliser Styled-JSX.
// .babelrc or whatever config file you use
{
"presets" : [
[
" next/babel " ,
{
"styled-jsx" : {
"plugins" : [ " @styled-jsx/plugin-sass " ]
}
}
]
]
}Si vous utilisez un monorepo, vous devrez peut-être ajouter la configuration de Babel vous-même à votre projet de livre de contes. Ajoutez simplement une configuration Babel à votre projet de livre de contes avec le contenu suivant pour commencer.
{
"presets" : [ " next/babel " ]
}Next.js vous permet de personnaliser la configuration PostCSS. Ainsi, cet addon gérera automatiquement votre configuration PostCSS pour vous.
Cela permet des choses cool comme zéro config tailwindcss! Voir l'exemple With-TailwindCSS pour référence! C'est un clone de l'exemple Tailwindcss de Next.js mis en place avec le livre de contes et cet addon.
Au revoir ../ ! Les importations absolues du répertoire racine fonctionnent très bien avec cet addon.
// All good!
import Button from 'components/button'
// Also good!
import styles from 'styles/HomePage.module.css'
export default function HomePage ( ) {
return (
< >
< h1 className = { styles . title } > Hello World </ h1 >
< Button />
</ >
)
} // preview.js
// Also ok in preview.js!
import 'styles/globals.scss'
// ... Next.js permet une configuration d'exécution qui vous permet d'importer une fonction getConfig pratique pour obtenir une certaine configuration définie dans votre fichier next.config.js à l'exécution.
Dans le contexte du livre de contes avec cet addon, vous pouvez vous attendre à ce que la fonction de configuration d'exécution de Next.js fonctionne très bien.
Remarque, car StoryBook ne rendra pas le serveur vos composants, vos composants ne verront que ce qu'ils voient normalement du côté du client (c'est-à-dire qu'ils ne verront pas serverRuntimeConfig mais verront publicRuntimeConfig ).
Par exemple, considérez la configuration suivante suivante.
// next.config.js
module . exports = {
serverRuntimeConfig : {
mySecret : 'secret' ,
secondSecret : process . env . SECOND_SECRET // Pass through env variables
} ,
publicRuntimeConfig : {
staticFolder : '/static'
}
} Les appels à getConfig renverraient l'objet suivant lorsqu'ils sont appelés dans le livre de contes:
{
"serverRuntimeConfig" : {},
"publicRuntimeConfig" : {
"staticFolder" : " /static "
}
}Next.js est livré avec beaucoup de choses gratuitement à l'extérieur de la boîte comme la prise en charge SASS, mais parfois nous ajoutons des modifications de configuration WebPack personnalisées à next.js. Cet addon s'occupe de la plupart des modifications de webpack que vous voudriez ajouter. Si Next.js prend en charge une fonctionnalité hors de la boîte, alors cet addon fera fonctionner cette fonctionnalité dans la boîte dans le livre de contes. Si Next.js ne prend pas en charge quelque chose hors de la boîte, mais le rend facile à configurer, alors cet addon fera la même chose pour cette chose pour le livre de contes. Si vous trouvez quelque chose que vous devez toujours configurer WebPack pour obtenir une fonctionnalité Next.js dans le livre de contes après avoir ajouté cet addon, c'est probablement un bug et n'hésitez pas à ouvrir un problème.
Toutes les modifications de webpack souhaitées pour le livre de contes doivent être apportées dans .storybook / main.js selon les documents de Storybook.
Remarque: Toutes les modifications WebPack ne sont pas des copies / coller entre next.config.js et .storybook/main.js Il est recommandé de faire votre recherche sur la façon de faire correctement votre modification de la configuration Webpack de Storybook et sur le fonctionnement de WebPack.
N'hésitez pas à apporter un exemple pour aider la communauté.
Vous trouverez ci-dessous un exemple de la façon d'ajouter le support SVGR au livre de contes avec cet addon. L'exemple complet peut être trouvé ici.
// .storybook/main.js
module . exports = {
// other config omitted for brevity
webpackFinal : async config => {
// this modifies the existing image rule to exclude .svg files
// since we want to handle those files with @svgr/webpack
const imageRule = config . module . rules . find ( rule => rule . test . test ( '.svg' ) )
imageRule . exclude = / .svg$ /
// configure .svg files to be loaded with @svgr/webpack
config . module . rules . push ( {
test : / .svg$ / ,
use : [ '@svgr/webpack' ]
} )
return config
}
} Le livre de contes gère la plupart des configurations de typeScript, mais cet addon ajoute une prise en charge supplémentaire pour la prise en charge de Next.js pour les importations absolues et les alias de chemin de module. En bref, il prend en compte la fondation et les chemins de votre tsconfig.json . Ainsi, un tsconfig.json comme celui ci-dessous fonctionnerait hors de la boîte.
{
"compilerOptions" : {
"baseUrl" : " . " ,
"paths" : {
"@/components/*" : [ " components/* " ]
}
}
} À l'heure actuelle, le seul format de configuration pris en charge pour next.js que ce plugin prend en charge est la version CommonJS de la configuration (ie next.config.js ). C'est principalement parce que je n'ai pas compris comment exiger un fichier .mjs à partir d'un addon au livre de contes (qui est lié aux modules CommonJS pour autant que je sache en ce moment). Si vous êtes en mesure d'aider, j'adorerais que vous puissiez contribuer à cette discussion pour obtenir un support pour la version .mjs si un tel support est même possible.
Si vous utilisez YARN V2 ou V3, vous pouvez rencontrer des problèmes où le livre de contes ne peut pas résoudre style-loader ou css-loader . Par exemple, vous pourriez obtenir des erreurs comme:
Module not found: Error: Can't resolve 'css-loader'
Module not found: Error: Can't resolve 'style-loader'
En effet Si c'est le cas pour vous, installez simplement le package directement.
Assurez-vous que vous traitez les importations d'images de la même manière que vous les traitez lorsque vous utilisez l'image suivante en développement normal.
Avant storybook-addon-next , les importations d'image ont juste importé le chemin brut vers l'image (par exemple 'static/media/stories/assets/plugin.svg' ). Lorsque vous utilisez des importations d'image storybook-addon-next de contes de contes, ce qui signifie que nous obtenons maintenant un objet lorsque nous importons une image. Par exemple:
{
"src" : " static/media/stories/assets/plugin.svg " ,
"height" : 48 ,
"width" : 48 ,
"blurDataURL" : " static/media/stories/assets/plugin.svg "
}Par conséquent, si quelque chose dans le livre de contes ne montre pas correctement l'image, assurez-vous de vous attendre à ce que l'objet soit renvoyé d'une importation au lieu du chemin d'actif.
Voir les images locales pour plus de détails sur la façon dont Next.js traite les importations d'images statiques.
À l'heure actuelle, l'utilisation next.config.mjs n'est pas prise en charge par cet addon. Voir suivante.config.js pour plus de détails. À l'heure actuelle, il vous est nécessaire d'utiliser l'extension .js à la place. N'hésitez pas à aider cette discussion pour obtenir cela soutenu.
Vous pourriez l'obtenir si vous utilisez le fil V2 ou V3. Voir les notes pour les utilisateurs de YARN V2 et V3 pour plus de détails.
Je suis ouvert à la discussion. N'hésitez pas à ouvrir un problème.
Cette documentation était-elle insuffisante pour vous?
Était-ce déroutant?
Était-ce ... oserais-je dire ... inexact?
Si l'un des éléments ci-dessus décrit vos sentiments de cette documentation. N'hésitez pas à ouvrir un problème.
