storybook addon next
v1.8.0
Este complemento se ha desapercido en favor de @Storybook/NextJS, que es el complemento oficial de Storybook para apoyar las funciones de Next.js en Storybook. ¡Apoya todo lo que hace storybook-addon-next y mucho más! Incluso trabajé en desarrollar esto con ellos, por lo que deberías estar en buenas manos.
Consulte los documentos de migración para obtener detalles sobre cómo migrar.
? No hay soporte de configuración para Next.js : ¿Cansado de escribir y depurar la configuración de Webpack? ¿Qué admite Next.js?
Componente de imagen de Next.js (soporte parcial)
Next.js enrutamiento
Sass/scss
Módulos CSS/SASS/SCSS
JSX de estilo
Postcss
Importaciones absolutas
Configuración de tiempo de ejecución
Configuración de Webpack personalizado
Mecanografiado
.js y no la extensión .mjs (es decir, next.config.js no next.config.mjs )Para ejecutar cualquier ejemplo, primero construya el complemento ejecutando
yarn builden la raíz de este repositorio.
Instale storybook-addon-next usando yarn :
yarn add --dev storybook-addon-next O npm :
npm install --save-dev storybook-addon-next // .storybook/main.js
module . exports = {
// other config ommited for brevity
addons : [
// ...
'storybook-addon-next'
// ...
]
}? ¡Eso es todo! Las características compatibles deben funcionar fuera de la caja.
Consulte la documentación para obtener más detalles sobre cómo funcionan las características compatibles en este complemento.
Si algo no funciona como era de esperar, no dude en abrir un problema.
Este complemento se puede pasar un objeto Opciones para la configuración adicional si es necesario.
Por ejemplo:
// .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 : El camino absoluto a la next.config.js Siguiente/imagen es notoriamente difícil trabajar con Storybook. ¡Este complemento le permite usar el componente Image de Next.js sin configuración!
Debido a que el componente de la imagen tiene características, como la optimización de imágenes, configuradas por opciones que requieren que el marco lea y procese el archivo de configuración Next.js, y no hay una función pública expuesta por Next.js para resolver y esas opciones, no es posible admitir esas características de manera estable.
Si desea ver esto mejor apoyado, no dude en contribuir a la discusión en el lado de Next.js o la discusión de nuestro lado
¡Las imágenes locales funcionan bien con este complemento! Tenga en cuenta que esta característica solo se agregó en 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 >
</ >
)
} ¡Las imágenes remotas también funcionan 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 >
</ >
)
} Todas Image de Next.js no están optimizadas automáticamente para usted.
Si se usa PlaceHolder = "Blur", el blurdataurl utilizado es el SRC de la imagen (desactivando así efectivamente al marcador de posición).
Vea este tema para obtener más discusión sobre cómo se manejan Image de Next.js para el libro de cuentos.
Este formato aún no es compatible con este complemento. Siéntase libre de abrir un problema si esto es algo que desea ver.
Esta solución se basa en gran medida en Storybook-Addon-Next-Router, por lo que un gran agradecimiento al lifeiscontent por proporcionar una buena solución de la que este complemento podría funcionar.
El enrutador de Next.js se roba automáticamente para usted para que cuando el enrutador interactúe, todas sus interacciones se registran automáticamente en la pestaña Acciones de libros de cuentos si tiene el complemento de las acciones.
Las anulaciones por historia se pueden hacer agregando una propiedad nextRouter a los parámetros de la historia. El complemento fusionará superficialmente lo que ponga aquí en el enrutador.
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"
}
}
}Vea este ejemplo para una referencia.
Los valores predeterminados globales se pueden establecer en Preview.js y se fusionarán superficialmente con el enrutador predeterminado.
export const parameters = {
nextRouter : {
path : '/some-default-path' ,
asPath : '/some-default-path' ,
query : { }
}
}Vea este ejemplo para una referencia.
Los valores predeterminados en el enrutador robado son los siguientes (consulte Globals para obtener más detalles sobre cómo funcionan los globales)
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 anula una función, pierde la integración de pestañas de acción automática y tiene que construirla usted mismo.
export const parameters = {
nextRouter : {
push ( ) {
// we lose the default implementation that logs the action into the action tab
}
}
} Hacer esto usted mismo se parece a esto (asegúrese de instalar el paquete @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 )
}
}
}Las hojas de estilo Global Sass/SCSS son compatibles sin ninguna configuración adicional. Simplemente importarlos en Preview.js
import '../styles/globals.scss' Esto incluirá automáticamente cualquiera de sus configuraciones SASS personalizadas en su archivo next.config.js .
En este momento, solo se admite la extensión
.jsde la configuración Next.js, no.mjs. Vea Next.config.js para obtener más detalles.
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 admite módulos CSS fuera de la caja, por lo que este complemento también lo admite.
// 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 >
)
}El CSS incorporado en la solución JS para Next.js es Styled-JSX, y este complemento también lo admite fuera de la caja, cero configuración.
// 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 HelloWorldTambién puede usar su propia configuración de Babel. Este es un ejemplo de cómo puede personalizar el estilo-JSX.
// .babelrc or whatever config file you use
{
"presets" : [
[
" next/babel " ,
{
"styled-jsx" : {
"plugins" : [ " @styled-jsx/plugin-sass " ]
}
}
]
]
}Si usa un Monorepo, es posible que deba agregar la configuración de Babel a su proyecto de libros de cuentos. Simplemente agregue una configuración de Babel a su proyecto de libro de cuentos con el siguiente contenido para comenzar.
{
"presets" : [ " next/babel " ]
}Next.js le permite personalizar la configuración PostCSS. Por lo tanto, este complemento manejará automáticamente su configuración PostCSS para usted.
¡Esto permite cosas geniales como cero configuración tallwindcss! ¡Vea el ejemplo con referencia con tailwindcss! Es un clon del ejemplo de las ondas de cola de Next.js configuradas con el libro de cuentos y este complemento.
Adiós ../ ! Las importaciones absolutas del directorio raíz funcionan bien con este complemento.
// 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 permite la configuración de tiempo de ejecución que le permite importar una función getConfig útil para obtener una configuración cierta definida en su archivo next.config.js en tiempo de ejecución.
En el contexto del libro de cuentos con este complemento, puede esperar que la función de configuración de tiempo de ejecución de Next.js funcione bien.
Nota, Debido a que Storybook no es un servidor renderizado sus componentes, sus componentes solo verán lo que normalmente ven en el lado del cliente (es decir, no verán serverRuntimeConfig , sino que verán publicRuntimeConfig ).
Por ejemplo, considere la siguiente configuración Next.js:
// next.config.js
module . exports = {
serverRuntimeConfig : {
mySecret : 'secret' ,
secondSecret : process . env . SECOND_SECRET // Pass through env variables
} ,
publicRuntimeConfig : {
staticFolder : '/static'
}
} Las llamadas a getConfig devolverían el siguiente objeto cuando se llame dentro del libro de cuentos:
{
"serverRuntimeConfig" : {},
"publicRuntimeConfig" : {
"staticFolder" : " /static "
}
}Next.js viene con muchas cosas de forma gratuita como soporte Sass, pero a veces agregamos modificaciones de configuración de Webpack personalizadas a Next.js. Este complemento se encarga de la mayoría de las modificaciones de Webpack que desea agregar. Si Next.js admite una función de la caja, entonces este complemento hará que esa función funcione de la caja en el libro de cuentos. Si Next.js no admite algo de la caja, pero facilita la configuración, entonces este complemento hará lo mismo para eso para el libro de cuentos. Si encuentra algo que aún necesita para configurar Webpack para obtener una función Next.js para que funcione en el libro de cuentos después de agregar este complemento, es probable que sea un error y no dude en abrir un problema.
Las modificaciones de Webpack deseadas para el libro de cuentos deben hacerse en .storybook/main.js de acuerdo con los documentos de Storybook.
Nota: No todas las modificaciones de Webpack son copiar/pegar entre next.config.js y .storybook/main.js . Se recomienda realizar su investigación sobre cómo hacer correctamente su modifo en la configuración de Webpack de Storybook y sobre cómo funciona Webpack.
No dude en contribuir con un ejemplo para ayudar a la comunidad.
A continuación se muestra un ejemplo de cómo agregar soporte SVGR al libro de cuentos con este complemento. El ejemplo completo se puede encontrar aquí.
// .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
}
} Storybook maneja la mayoría de las configuraciones de TypeScript, pero este complemento agrega soporte adicional para el soporte de Next.js para las importaciones absolutas y los alias de ruta del módulo. En resumen, tiene en cuenta la base y las rutas de su tsconfig.json . Por lo tanto, un tsconfig.json como el siguiente funcionaría fuera de la caja.
{
"compilerOptions" : {
"baseUrl" : " . " ,
"paths" : {
"@/components/*" : [ " components/* " ]
}
}
} En este momento, el único formato de configuración compatible para Next.js que es compatible con este complemento es la versión CommonJS de la configuración (es decir, next.config.js ). Esto se debe principalmente a que no he descubierto cómo requerir un archivo .mjs de un complemento de libros de cuentos (que está vinculado a los módulos CommonJS hasta donde yo sé en este momento). Si puede ayudar, me encantaría si pudiera contribuir a esta discusión para obtener apoyo para la versión .mjs si tal soporte es posible.
Si está utilizando Yarn V2 o V3, puede encontrarse con problemas en los que el libro de cuentos no puede resolver style-loader o css-loader . Por ejemplo, puede obtener errores como:
Module not found: Error: Can't resolve 'css-loader'
Module not found: Error: Can't resolve 'style-loader'
Esto se debe a que esas versiones de hilo tienen diferentes reglas de resolución de paquetes que el hilo v1.x. Si este es el caso para usted, simplemente instale el paquete directamente.
Asegúrese de tratar la imagen de la imagen de la misma manera que las trata cuando usa la siguiente imagen en el desarrollo normal.
Antes de storybook-addon-next , las importaciones de imágenes acaban de importar la ruta sin procesar a la imagen (por ejemplo 'static/media/stories/assets/plugin.svg' ). Cuando se usa storybook-addon-next Imports, las importaciones funcionan la "forma next.js", lo que significa que ahora obtenemos un objeto cuando importamos una imagen. Por ejemplo:
{
"src" : " static/media/stories/assets/plugin.svg " ,
"height" : 48 ,
"width" : 48 ,
"blurDataURL" : " static/media/stories/assets/plugin.svg "
}Por lo tanto, si algo en el libro de cuentos no muestra la imagen correctamente, asegúrese de esperar que el objeto se devuelva de una importación en lugar de solo la ruta de los activos.
Vea las imágenes locales para obtener más detalles sobre cómo NEXT.JS trata las importaciones de imágenes estáticas.
En este momento, usar next.config.mjs no es compatible con este complemento. Vea Next.config.js para obtener más detalles. En este momento, es necesario que use la extensión .js . Siéntase libre de ayudar en esta discusión para que esto apoye.
Puede obtener esto si está usando Yarn V2 o V3. Consulte las notas para los usuarios de Yarn V2 y V3 para obtener más detalles.
Estoy abierto a la discusión. Siéntase libre de abrir un problema.
¿Fue esta documentación insuficiente para usted?
¿Fue confuso?
¿Fue ... me atrevo a decir ... inexacto?
Si alguno de los anteriores describe sus sentimientos de esta documentación. Siéntase libre de abrir un problema.
