storybook addon next
v1.8.0
Dieses Addon wurde zugunsten von @storybook/NextJs veraltet, das offizielle Addon für die Unterstützung von Next.js in Storybook. Es unterstützt alles storybook-addon-next tut und vieles mehr! Ich habe sogar daran gearbeitet, dies mit ihnen zu entwickeln, also sollten Sie in guten Händen sein.
Wenden Sie sich an die Migrationsdokumente, um Informationen zum Migrieren zu erhalten.
? Keine Konfigurationsunterstützung für Next.js : Müde, Webpack -Konfiguration zu schreiben und zu debuggen? Was als nächstes.js unterstützt, ermöglicht dieses Addon in Storybook
Next.js 'Bildkomponente (teilweise Unterstützung)
Weiter.js Routing
Sass/SCSS
CSS/SASS/SCSS -Module
Gestylt JSX
Postcss
Absolute Importe
Laufzeitkonfiguration
Benutzerdefinierte Webpack -Konfiguration
Typoskript
.js und nicht die .mjs -Erweiterung (dh next.config.js nicht next.config.mjs )Um ein beliebiges Beispiel auszuführen, erstellen Sie zuerst das Addon, indem Sie
yarn buildin der Wurzel dieses Repo ausführen.
Installieren Sie storybook-addon-next mit yarn :
yarn add --dev storybook-addon-next Oder npm :
npm install --save-dev storybook-addon-next // .storybook/main.js
module . exports = {
// other config ommited for brevity
addons : [
// ...
'storybook-addon-next'
// ...
]
}? Das ist es! Die unterstützten Merkmale sollten nicht über die Box gelangen.
Weitere Informationen zur Funktionsweise der unterstützten Funktionen in diesem Addon finden Sie in der Dokumentation.
Wenn etwas nicht funktioniert, wie Sie es erwarten würden, können Sie sich gerne ein Problem eröffnen.
Dieses Addon kann bei Bedarf ein Optionsobjekt für die Addionalkonfiguration übergeben werden.
Zum Beispiel:
// .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 : Der absolute Weg zum next.config.js Als nächstes/Bild ist es notorisch schwierig, mit einem Storybook zu arbeiten. Mit diesem Addon können Sie Image von Next.js ohne Konfiguration verwenden!
Da die Bildkomponente Funktionen wie die Bildoptimierung enthält, die durch Optionen konfiguriert sind, für die die nächste.js -Konfigurationsdatei vom Framework gelesen und verarbeitet werden muss, und keine öffentliche Funktion von Next.js zum Auflösen ausgesetzt ist, ist es nicht möglich, diese Funktionen stabil zu unterstützen.
Wenn Sie dies besser unterstützt sehen möchten, können Sie sich gerne zur Diskussion über die Seite von Next.js oder die Diskussion auf unserer Seite beitragen
Lokale Bilder funktionieren gut mit diesem Addon! Denken Sie daran, dass diese Funktion nur im nächsten.js v11 hinzugefügt wurde.
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 >
</ >
)
} Remote -Bilder funktionieren auch gut!
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 >
</ >
)
} Alle nächsten.js Image sind für Sie automatisch nicht optimiert.
Wenn Platzhalter = "Blur" verwendet wird, ist der verwendete Blurdataurl die SRC des Bildes (somit den Platzhalter effektiv deaktiviert).
Weitere Image finden Sie in dieser Ausgabe, um weitere Diskussionen darüber zu erhalten.
Dieses Format wird von diesem Addon noch nicht unterstützt. Fühlen Sie sich frei, ein Problem zu eröffnen, wenn dies etwas ist, das Sie sehen möchten.
Diese Lösung basiert stark auf lifeiscontent Storybook-Addon-Next-Router.
Next.js 'Router ist automatisch für Sie gestoßen, so dass, wenn der Router interagiert wird, alle seine Interaktionen automatisch auf der Registerkarte "Storybook -Aktionen" protokolliert werden, wenn Sie die Aktionen addon haben.
Überschreibungen pro Story können durch Hinzufügen einer nextRouter Eigenschaft zu den Story-Parametern durchgeführt werden. Das Addon wird flach verschmolzen, was Sie hier in den Router gesteckt haben.
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"
}
}
}In diesem Beispiel finden Sie eine Referenz.
Globale Standardeinstellungen können in Preview.js festgelegt werden und werden mit dem Standardrouter flach verschmolzen.
export const parameters = {
nextRouter : {
path : '/some-default-path' ,
asPath : '/some-default-path' ,
query : { }
}
}In diesem Beispiel finden Sie eine Referenz.
Die Standardwerte im Stubbed -Router sind wie folgt (siehe Global, weitere Einzelheiten zur Funktionsweise von Globalen)
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
} Wenn Sie eine Funktion überschreiben, verlieren Sie die automatische Integration der Aktion Registerkarte und müssen sie selbst erstellen.
export const parameters = {
nextRouter : {
push ( ) {
// we lose the default implementation that logs the action into the action tab
}
}
} Wenn Sie dies selbst tun, sieht es so aus (stellen Sie sicher, dass Sie das Paket @storybook/addon-actions installieren):
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 )
}
}
}Globale SASS/SCSS -Stylesheets werden auch ohne zusätzliche Konfiguration unterstützt. Importieren Sie sie einfach in Preview.js
import '../styles/globals.scss' Dies enthält automatisch eine Ihrer benutzerdefinierten SASS -Konfigurationen in der next.config.js -Datei.
Im Moment wird nur die
.js-Erweiterung der nächsten.js -Konfiguration unterstützt, nicht.mjs. Weitere Informationen finden Sie unter next.config.js.
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 unterstützt CSS -Module außerhalb der Box, sodass dieses Addon es auch unterstützt.
// 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 >
)
}Das integrierte CSS in JS-Lösung für Next.js ist gestylt-JSX, und dieses Addon unterstützt dies auch außerhalb der Box, Null-Konfiguration.
// 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 HelloWorldSie können auch Ihre eigene Babel -Konfiguration verwenden. Dies ist ein Beispiel dafür, wie Sie Styled-JSX anpassen können.
// .babelrc or whatever config file you use
{
"presets" : [
[
" next/babel " ,
{
"styled-jsx" : {
"plugins" : [ " @styled-jsx/plugin-sass " ]
}
}
]
]
}Wenn Sie einen Monorepo verwenden, müssen Sie möglicherweise die Babel -Konfiguration selbst zu Ihrem Storybook -Projekt hinzufügen. Fügen Sie Ihrem Storybook -Projekt einfach eine Babel -Konfiguration mit dem folgenden Inhalt hinzu, um loszulegen.
{
"presets" : [ " next/babel " ]
}Mit jungen.Js können Sie die PostCSS -Konfiguration anpassen. Daher verarbeitet dieses Addon Ihre Postcss -Konfiguration automatisch für Sie.
Dies ermöglicht coole Dinge wie null Konfigurationswindwindcss! Sehen Sie sich das Beispiel mit Schwanzwindcss als Referenz an! Es ist ein Klon von Next.
Auf Wiedersehen ../ ! Absolute Importe aus dem Stammverzeichnis funktionieren gut mit diesem 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 ermöglicht eine Laufzeitkonfiguration, mit der Sie eine praktische getConfig -Funktion importieren können, um eine bestimmte Konfiguration in Ihrer next.config.js -Datei zur Laufzeit zu definieren.
Im Kontext des Storybooks mit diesem Addon können Sie erwarten, dass die Feature der Laufzeitkonfiguration von Next.js einwandfrei funktioniert.
Beachten Sie, dass Ihre Komponenten, da das Storybook keine Server -Server macht, Ihre Komponenten nur sehen, was sie normalerweise auf der Client -Seite sehen (dh sie werden nicht serverRuntimeConfig sehen, aber publicRuntimeConfig sehen).
Betrachten Sie beispielsweise die folgende NEXT.JS -Konfiguration:
// next.config.js
module . exports = {
serverRuntimeConfig : {
mySecret : 'secret' ,
secondSecret : process . env . SECOND_SECRET // Pass through env variables
} ,
publicRuntimeConfig : {
staticFolder : '/static'
}
} Anrufe zum getConfig würden das folgende Objekt zurückgeben, wenn sie innerhalb von Storybook angerufen werden:
{
"serverRuntimeConfig" : {},
"publicRuntimeConfig" : {
"staticFolder" : " /static "
}
}Next.js wird mit vielen Dingen kostenlos wie SASS -Unterstützung kostenlos geliefert, aber manchmal fügen wir zu Next.js. Dieses Addon kümmert sich um die meisten Webpack -Modifikationen, die Sie hinzufügen möchten. Wenn NEXT.JS eine Funktion nicht in der Box unterstützt, wird dieses Addon diese Funktion in Storybook herausstellen. Wenn Next.js etwas nicht in der Box unterstützt, aber es einfach zu konfigurieren macht, dann wird dieses Addon das Gleiche für das Ding für Storybook tun. Wenn Sie etwas finden, das Sie weiterhin konfigurieren müssen, um WebPack zu konfigurieren, um eine Nächste.js -Funktion für das Handwerk nach dem Hinzufügen dieses Addon zu erhalten, ist dies wahrscheinlich ein Fehler. Bitte öffnen Sie ein Problem.
Alle für das Storybook gewünschten Webpack -Modifikationen sollten in .Storybook/main.js gemäß den Dokumenten von Storybook vorgenommen werden.
HINWEIS: Nicht alle Webpack-Modifikationen sind zwischen next.config.js und .storybook/main.js kopieren/einfügen. Es wird empfohlen, Ihre Forschung zu machen, wie Sie Ihre Modifikation in der WebPack -Konfiguration von Storybook und der Funktionsweise von WebPack ordnungsgemäß erstellen können.
Bitte zögern Sie nicht, ein Beispiel für die Community beizutragen.
Im Folgenden finden Sie ein Beispiel dafür, wie Sie mit diesem Addon SVGR -Support zu einem Storybook hinzufügen. Das vollständige Beispiel finden Sie hier.
// .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 übernimmt die meisten Typ -Konfigurationen, aber dieses Addon fügt zusätzliche Unterstützung für die Unterstützung von Next.js für absolute Importe und Modulpfad -Aliase hinzu. Kurz gesagt, es berücksichtigt die Basis- und Pfade Ihres tsconfig.json . Somit würde ein tsconfig.json wie der unten die Box herausarbeiten.
{
"compilerOptions" : {
"baseUrl" : " . " ,
"paths" : {
"@/components/*" : [ " components/* " ]
}
}
} Das einzige unterstützte Konfigurationsformat für Next.js, das dieses Plugin unterstützt, ist die CommonJS -Version der Konfiguration (dh next.config.js ). Dies liegt hauptsächlich daran, dass ich nicht herausgefunden habe, wie ich eine .mjs -Datei von einem Storybook -Addon benötigt (das an CommonJS -Module gebunden ist, soweit ich gerade weiß). Wenn Sie in der Lage sind zu helfen, würde ich es lieben, wenn Sie zu dieser Diskussion beitragen könnten, um Unterstützung für die .mjs -Version zu erhalten, wenn eine solche Unterstützung überhaupt möglich ist.
Wenn Sie Garn V2 oder V3 verwenden, können Sie auf Probleme stoßen, bei denen Storybook style-loader oder css-loader nicht beheben kann. Zum Beispiel können Sie Fehler wie:
Module not found: Error: Can't resolve 'css-loader'
Module not found: Error: Can't resolve 'style-loader'
Dies liegt daran, dass diese Versionen von Garn unterschiedliche Regeln für Paketlösungen haben als Garn v1.x. Wenn dies für Sie der Fall ist, installieren Sie das Paket einfach direkt.
Stellen Sie sicher, dass Sie Bildimporte so behandeln, wie Sie sie behandeln, wenn Sie das nächste Bild in der normalen Entwicklung verwenden.
Vor storybook-addon-next importierte Image den RAW-Pfad nur zum Bild (z 'static/media/stories/assets/plugin.svg' ). Bei Verwendung von storybook-addon-next Bild-Importen arbeiten die "Next.js Way", was bedeutet, dass wir jetzt ein Objekt erhalten, wenn wir ein Bild importieren. Zum Beispiel:
{
"src" : " static/media/stories/assets/plugin.svg " ,
"height" : 48 ,
"width" : 48 ,
"blurDataURL" : " static/media/stories/assets/plugin.svg "
}Wenn etwas in Storybook das Bild nicht richtig anzeigt, stellen Sie sicher, dass Sie erwarten, dass das Objekt von einem Import zurückgegeben wird, anstatt nur auf den Asset -Pfad.
Weitere Informationen finden Sie in lokalen Bildern, um wie Next.js statische Bildimporte behandelt.
Im Moment wird mit next.config.mjs von diesem Addon nicht unterstützt. Weitere Informationen finden Sie unter next.config.js. Im Moment ist es erforderlich, dass Sie stattdessen die .js -Erweiterung verwenden. Fühlen Sie sich frei, diese Diskussion zu helfen, um dies zu unterstützen.
Sie können dies bekommen, wenn Sie Garn V2 oder V3 verwenden. Weitere Informationen finden Sie unter Notizen für Garn V2 und V3 -Benutzer.
Ich bin offen für Diskussionen. Fühlen Sie sich frei, ein Problem zu eröffnen.
War diese Dokumentation für Sie nicht ausreichend?
War es verwirrend?
War es ... wage ich zu sagen ... ungenau?
Wenn eines der oben genannten Ihre Gefühle dieser Dokumentation beschreibt. Fühlen Sie sich frei, ein Problem zu eröffnen.
