storybook addon next
v1.8.0
Este addon foi descontinuado em favor do @storybook/NextJs, que é o Addon oficial do Storybook para apoiar os recursos do Next.JS no Storybook. Ele suporta tudo storybook-addon-next faz e muito mais! Eu até trabalhei para desenvolver isso com eles, para que você deve estar em boas mãos.
Consulte os documentos de migração para obter detalhes sobre como migrar.
? Nenhum suporte de configuração para Next.js : Cansado de escrever e depurar a Webpack Config? O que Next.js suporta
Componente de imagem do Next.JS (suporte parcial)
Next.js roteamento
SASS/SCSS
Módulos CSS/SASS/SCSS
JSX denominado
POSTCSS
Importações absolutas
Config de tempo de execução
Config personalizado do WebPack
TypeScript
.js e não a extensão .mjs (ou seja, next.config.js não a next.config.mjs )Para executar qualquer exemplo, primeiro construa o addon executando
yarn buildna raiz deste repositório.
Instale storybook-addon-next usando 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'
// ...
]
}? É isso! Os recursos suportados devem funcionar fora da caixa.
Consulte a documentação para obter mais detalhes sobre como os recursos suportados funcionam neste complemento.
Se algo não funcionar como você esperaria, fique à vontade para abrir um problema.
Este addon pode ser passado um objeto de opções para configuração adcional, se necessário.
Por exemplo:
// .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 : o caminho absoluto para o next.config.js O próximo/imagem é notoriamente difícil de trabalhar com o Storybook. Este addon permite que você use o componente Image Next.JS sem configuração!
Como o componente da imagem possui recursos, como otimização de imagem, configurados por opções que exigem o arquivo de configuração do próximo.js a ser lido e processado pela estrutura e não há função pública exposta pelo Next.js para resolver e essas opções, não é possível suportar esses recursos de maneira estável.
Se você quiser ver isso melhor apoiado, sinta -se à vontade para contribuir com a discussão do lado de Next.JS ou a discussão do nosso lado
As imagens locais funcionam bem com este complemento! Lembre -se de que esse recurso foi adicionado apenas no próximo.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 >
</ >
)
} Imagens remotas também funcionam muito bem!
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 do próximo.js são automaticamente não otimizadas para você.
Se estiver usado em espaço reservado = "Blur", o Blurdataurl usado é o SRC da imagem (desativando efetivamente o espaço reservado).
Veja esta edição para obter mais discussão sobre como o próximo.js Image são tratadas para o Storybook.
Este formato ainda não é suportado por este complemento. Sinta -se à vontade para abrir um problema se isso é algo que você deseja ver.
Esta solução é fortemente baseada no Storybook lifeiscontent Addon-Next-Router.
O roteador do Next.JS é automaticamente matizado para você para que, quando o roteador for interagido, todas as suas interações sejam automaticamente registradas na guia Ações do livro de histórias, se você tiver as ações.
As substituições por história podem ser feitas adicionando uma propriedade nextRouter aos parâmetros da história. O addon se fundirá superficialmente o que você colocar aqui no roteador.
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"
}
}
}Veja este exemplo para uma referência.
Os padrões globais podem ser definidos no visualize.js e serão mesclados superficiais com o roteador padrão.
export const parameters = {
nextRouter : {
path : '/some-default-path' ,
asPath : '/some-default-path' ,
query : { }
}
}Veja este exemplo para uma referência.
Os valores padrão no roteador Stubbed são os seguintes (consulte Globals para obter mais detalhes sobre como os globais funcionam)
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
} Se você substituir uma função, perde a integração da guia Ação automática e precisará construí -la.
export const parameters = {
nextRouter : {
push ( ) {
// we lose the default implementation that logs the action into the action tab
}
}
} Fazer isso você mesmo se parece com isso (certifique-se de instalar o pacote de @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 )
}
}
}As folhas de estilo SASS/SCSS globais também são suportadas sem nenhuma configuração adicional. Apenas importá -los para visualizar.js
import '../styles/globals.scss' Isso incluirá automaticamente qualquer uma das suas configurações SASS personalizadas no seu arquivo next.config.js .
No momento, apenas a extensão
.jsda próxima configuração.js é suportada, não.mjs. Consulte Next.config.js para obter mais detalhes.
const path = require ( 'path' )
module . exports = {
// any options here are included in sass compilation for your stories
sassOptions : {
includePaths : [ path . join ( __dirname , 'styles' ) ]
}
}O Next.js suporta módulos CSS para fora da caixa, para que este addon também o ofereça.
// 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 >
)
}O CSS embutido na solução JS para o Next.js é Styled-JSX, e esse complemento também suporta isso pronta para uso, Zero 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 HelloWorldVocê também pode usar sua própria configuração de Babel. Este é um exemplo de como você pode personalizar o Styled-JSX.
// .babelrc or whatever config file you use
{
"presets" : [
[
" next/babel " ,
{
"styled-jsx" : {
"plugins" : [ " @styled-jsx/plugin-sass " ]
}
}
]
]
}Se você usar um Monorepo, pode ser necessário adicionar o Babel Config -se ao seu projeto de livro de histórias. Basta adicionar uma configuração Babel ao seu projeto de livro de histórias com o conteúdo a seguir para começar.
{
"presets" : [ " next/babel " ]
}Next.js permite personalizar a configuração do PostCSS. Portanto, este Addon lidará automaticamente com sua configuração PostCSS para você.
Isso permite coisas legais como Zero Config Tailwindcss! Veja o exemplo do exemplo de referência! É um clone do Exemplo de Tailwindcss da Next.JS criado com o Storybook e este addon.
Adeus ../ ! As importações absolutas do diretório raiz funcionam muito bem com 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 a configuração de tempo de execução, que permite importar uma função getConfig útil para obter determinada configuração definida no seu arquivo next.config.js no tempo de execução.
No contexto do livro de histórias com este Addon, você pode esperar o recurso de configuração de tempo de execução do Next.JS para funcionar muito bem.
Observe que, como o Storybook não renderiza seus componentes, seus componentes verão apenas o que eles normalmente vêem no lado do cliente (ou seja, eles não verão serverRuntimeConfig , mas verão publicRuntimeConfig ).
Por exemplo, considere o seguinte a seguir.
// next.config.js
module . exports = {
serverRuntimeConfig : {
mySecret : 'secret' ,
secondSecret : process . env . SECOND_SECRET // Pass through env variables
} ,
publicRuntimeConfig : {
staticFolder : '/static'
}
} As chamadas para getConfig retornariam o seguinte objeto quando chamadas no Storybook:
{
"serverRuntimeConfig" : {},
"publicRuntimeConfig" : {
"staticFolder" : " /static "
}
}Next.js vem com muitas coisas gratuitamente, como o suporte SASS, mas às vezes adicionamos modificações personalizadas de configuração do WebPack ao Next.js. Este Addon cuida da maioria das modificações do WebPack que você deseja adicionar. Se o Next.js suportar um recurso fora da caixa, esse complemento fará com que esse recurso funcione fora da caixa no livro de histórias. Se Next.js não suportar algo fora da caixa, mas facilitará a configuração, esse addon fará o mesmo por essa coisa para o Storybook. Se você encontrar algo que ainda precisa configurar o WebPack para obter um recurso Next.js para funcionar no Storybook depois de adicionar esse complemento, isso provavelmente é um bug e, por favor, sinta -se à vontade para abrir um problema.
Quaisquer modificações de Webpack desejadas para o Storybook devem ser feitas no .StoryBook/Main.js de acordo com os documentos do Storybook.
NOTA: Nem todas as modificações do WebPack são copiadas/coletas entre next.config.js e .storybook/main.js . É recomendável fazer sua pesquisa sobre como fazer sua modificação na configuração do WebPack do Storybook e sobre como funciona o WebPack.
Sinta -se à vontade para contribuir com um exemplo para ajudar a comunidade.
Abaixo está um exemplo de como adicionar suporte ao SVGR ao Storybook com este complemento. O exemplo completo pode ser encontrado aqui.
// .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
}
} O StoryBook lida com a maioria das configurações do TypeScript, mas esse addon adiciona suporte adicional para o suporte do Next.JS para importações absolutas e aliases de caminho do módulo. Em resumo, leva em consideração o tsconfig.json BASEURL e os caminhos. Assim, um tsconfig.json como o abaixo funcionaria fora da caixa.
{
"compilerOptions" : {
"baseUrl" : " . " ,
"paths" : {
"@/components/*" : [ " components/* " ]
}
}
} No momento, o único formato de configuração suportado para Next.js que este plug -in suporta é a versão Commonjs da configuração (ou seja, next.config.js ). Isso ocorre principalmente porque eu não descobri como exigir um arquivo .mjs de um addon do livro de histórias (que está vinculado aos módulos Commonjs, tanto quanto eu sei agora). Se você puder ajudar, eu adoraria se você pudesse contribuir com essa discussão para obter suporte para a versão .mjs se esse suporte for possível.
Se você estiver usando o YARN V2 ou V3, poderá ter problemas em que o Storybook não pode resolver style-loader ou css-loader . Por exemplo, você pode obter erros como:
Module not found: Error: Can't resolve 'css-loader'
Module not found: Error: Can't resolve 'style-loader'
Isso ocorre porque essas versões de fios têm diferentes regras de resolução de pacotes que o YARN V1.X. Se for esse o caso, basta instalar o pacote diretamente.
Verifique se você está tratando as importações de imagem da mesma maneira que as trata ao usar a próxima imagem no desenvolvimento normal.
Antes storybook-addon-next , a imagem importa apenas importou o caminho bruto para a imagem (por exemplo 'static/media/stories/assets/plugin.svg' ). Ao usar as importações de imagem storybook-addon-next funcione o "Next.js Way", o que significa que agora obtemos um objeto quando importamos uma imagem. Por exemplo:
{
"src" : " static/media/stories/assets/plugin.svg " ,
"height" : 48 ,
"width" : 48 ,
"blurDataURL" : " static/media/stories/assets/plugin.svg "
}Portanto, se algo no livro de histórias não estiver mostrando a imagem corretamente, espere que o objeto seja devolvido de uma importação em vez de apenas o caminho do ativo.
Veja imagens locais para obter mais detalhes sobre como o próximo.js trata as importações de imagens estáticas.
No momento, usando next.config.mjs , não é suportado por este complemento. Consulte Next.config.js para obter mais detalhes. No momento, é necessário que você use a extensão .js . Sinta -se à vontade para ajudar nessa discussão para apoiar isso.
Você pode conseguir isso se estiver usando o YARN V2 ou V3. Consulte Notas para usuários de Yarn V2 e V3 para obter mais detalhes.
Estou aberto à discussão. Sinta -se à vontade para abrir um problema.
Esta documentação foi insuficiente para você?
Foi confuso?
Foi ... ouso dizer ... impreciso?
Se alguma das opções acima descrever seus sentimentos desta documentação. Sinta -se à vontade para abrir um problema.
