storybook addon next
v1.8.0
Addon ini telah digunakan untuk mendukung @Storybook/NextJS yang merupakan addon resmi buku cerita untuk mendukung fitur Next.js di Storybook. Ini mendukung semua storybook-addon-next dan banyak lagi! Saya bahkan bekerja mengembangkan ini dengan mereka sehingga Anda harus berada di tangan yang baik.
Konsultasikan dengan dokumen migrasi untuk perincian tentang cara bermigrasi.
? Tidak ada dukungan konfigurasi untuk selanjutnya . What Next.js mendukung di luar kotak, addon ini memungkinkan dalam buku cerita
Komponen Gambar Next.js (Dukungan Parsial)
Routing Next.js
Sass/SCSS
Modul CSS/SASS/SCSS
JSX yang ditata
PostCSS
Impor absolut
Runtime config
Konfigurasi webpack khusus
Naskah
.js dan bukan ekstensi .mjs (yaitu next.config.js not next.config.mjs )Untuk menjalankan contoh apa pun, pertama -tama bangun addon dengan menjalankan
yarn builddi akar repo ini.
Instal storybook-addon-next Menggunakan yarn :
yarn add --dev storybook-addon-next Atau npm :
npm install --save-dev storybook-addon-next // .storybook/main.js
module . exports = {
// other config ommited for brevity
addons : [
// ...
'storybook-addon-next'
// ...
]
}?? Itu saja! Fitur yang didukung harus bekerja di luar kotak.
Lihat dokumentasi untuk detail lebih lanjut tentang bagaimana fitur yang didukung bekerja di addon ini.
Jika sesuatu tidak berhasil seperti yang Anda harapkan, jangan ragu untuk membuka masalah.
Addon ini dapat diloloskan objek opsi untuk konfigurasi tambahan jika diperlukan.
Misalnya:
// .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 : Jalur absolut ke next.config.js Next/Image terkenal sulit untuk bekerja dengan Storybook. Addon ini memungkinkan Anda untuk menggunakan komponen Image Next.js tanpa konfigurasi!
Karena komponen gambar memiliki fitur, seperti pengoptimalan gambar, dikonfigurasi oleh opsi yang memerlukan file konfigurasi berikutnya.
Jika Anda ingin melihat ini didukung dengan lebih baik, jangan ragu untuk berkontribusi pada diskusi di sisi berikutnya.
Gambar lokal bekerja dengan baik dengan addon ini! Perlu diingat bahwa fitur ini hanya ditambahkan di 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 >
</ >
)
} Gambar jarak jauh juga berfungsi dengan baik!
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 >
</ >
)
} Semua Image selanjutnya.js S secara otomatis tidak dioptimalkan untuk Anda.
Jika placeholder = "blur" digunakan, blurdataurl yang digunakan adalah SRC dari gambar (dengan demikian secara efektif menonaktifkan placeholder).
Lihat masalah ini untuk diskusi lebih lanjut tentang bagaimana Image selanjutnya.js ditangani untuk buku cerita.
Format ini belum didukung oleh addon ini. Jangan ragu untuk membuka masalah jika ini adalah sesuatu yang ingin Anda lihat.
Solusi ini sangat didasarkan pada buku cerita-addon-next-router sehingga terima kasih banyak kepada lifeiscontent untuk memberikan solusi yang baik yang dapat dikerjakan oleh addon ini.
Router Next.js secara otomatis dibatalkan untuk Anda sehingga ketika router berinteraksi dengan, semua interaksinya secara otomatis dicatat ke tab Tindakan Buku Story jika Anda memiliki addon tindakan.
Pergantian per-story dapat dilakukan dengan menambahkan properti nextRouter ke parameter cerita. Addon akan dengan dangkal menggabungkan apa pun yang Anda masukkan ke sini ke dalam router.
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"
}
}
}Lihat contoh ini untuk referensi.
Default global dapat ditetapkan dalam preview.js dan akan digabungkan dengan router default.
export const parameters = {
nextRouter : {
path : '/some-default-path' ,
asPath : '/some-default-path' ,
query : { }
}
}Lihat contoh ini untuk referensi.
Nilai default pada router yang tersumbat adalah sebagai berikut (lihat Global untuk detail lebih lanjut tentang cara kerja global)
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
} Jika Anda mengganti fungsi, Anda kehilangan integrasi tab Tindakan Otomatis dan harus membangunnya sendiri.
export const parameters = {
nextRouter : {
push ( ) {
// we lose the default implementation that logs the action into the action tab
}
}
} Melakukan ini sendiri terlihat seperti ini (pastikan Anda menginstal paket @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 )
}
}
}Global Sass/SCSS Stylesheet didukung tanpa konfigurasi tambahan juga. Cukup impor ke preview.js
import '../styles/globals.scss' Ini secara otomatis akan menyertakan konfigurasi sass khusus Anda di file next.config.js Anda.
Saat ini hanya ekstensi
.jsdari config next.js yang didukung, bukan.mjs. Lihat selanjutnya.config.js untuk lebih jelasnya.
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 mendukung modul CSS di luar kotak sehingga addon ini juga mendukungnya.
// 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 >
)
}Solusi Built In CSS dalam JS untuk Next.js ditata-JSX, dan addon ini mendukung itu di luar kotak juga, nol konfigurasi.
// 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 HelloWorldAnda juga dapat menggunakan konfigurasi Babel Anda sendiri. Ini adalah contoh bagaimana Anda dapat menyesuaikan gaya-jsx.
// .babelrc or whatever config file you use
{
"presets" : [
[
" next/babel " ,
{
"styled-jsx" : {
"plugins" : [ " @styled-jsx/plugin-sass " ]
}
}
]
]
}Jika Anda menggunakan monorepo, Anda mungkin perlu menambahkan konfigurasi Babel sendiri ke proyek buku cerita Anda. Cukup tambahkan konfigurasi Babel ke proyek buku cerita Anda dengan konten berikut untuk memulai.
{
"presets" : [ " next/babel " ]
}Next.js memungkinkan Anda menyesuaikan konfigurasi postcss. Dengan demikian addon ini akan secara otomatis menangani konfigurasi postcss Anda untuk Anda.
Ini memungkinkan untuk hal -hal keren seperti nol config tailwindcss! Lihat contoh dengan-tailwindcss untuk referensi! Ini adalah klon dari contoh Tailwindcss Next.js yang diatur dengan buku cerita dan addon ini.
Selamat tinggal ../ ! Impor absolut dari direktori root bekerja dengan baik dengan addon ini.
// 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 memungkinkan konfigurasi runtime yang memungkinkan Anda mengimpor fungsi getConfig yang praktis untuk mendapatkan konfigurasi tertentu yang ditentukan dalam file next.config.js Anda saat runtime.
Dalam konteks buku cerita dengan addon ini, Anda dapat mengharapkan fitur konfigurasi runtime berikutnya.
Catatan, karena Storybook tidak membuat komponen Anda, komponen Anda hanya akan melihat apa yang biasanya mereka lihat di sisi klien (yaitu mereka tidak akan melihat serverRuntimeConfig tetapi akan melihat publicRuntimeConfig ).
Misalnya, pertimbangkan konfigurasi berikutnya.js berikut:
// next.config.js
module . exports = {
serverRuntimeConfig : {
mySecret : 'secret' ,
secondSecret : process . env . SECOND_SECRET // Pass through env variables
} ,
publicRuntimeConfig : {
staticFolder : '/static'
}
} Panggilan untuk getConfig akan mengembalikan objek berikut ketika dipanggil dalam buku cerita:
{
"serverRuntimeConfig" : {},
"publicRuntimeConfig" : {
"staticFolder" : " /static "
}
}Next.js hadir dengan banyak hal secara gratis di luar kotak seperti dukungan sass, tetapi kadang -kadang kami menambahkan modifikasi konfigurasi webpack khusus ke Next.js. Addon ini menangani sebagian besar modifikasi webpack yang ingin Anda tambahkan. Jika Next.js mendukung fitur di luar kotak, maka addon ini akan membuat fitur itu berfungsi di luar kotak di Storybook. Jika Next.js tidak mendukung sesuatu di luar kotak, tetapi membuatnya mudah untuk dikonfigurasi, maka addon ini akan melakukan hal yang sama untuk hal itu untuk buku cerita. Jika Anda menemukan sesuatu yang masih perlu Anda konfigurasikan Webpack untuk mendapatkan fitur Next.js untuk bekerja di Storybook setelah menambahkan addon ini, ini kemungkinan bug dan silakan membuka masalah.
Setiap modifikasi webpack yang diinginkan untuk buku cerita harus dibuat di .Storybook/Main.js Menurut dokumen Storybook.
Catatan: Tidak semua modifikasi webpack dapat disalin/dapat ditempel antara next.config.js dan .storybook/main.js . Disarankan untuk melakukan penelitian Anda tentang cara membuat modifikasi Anda dengan benar ke konfigurasi webpack Storybook dan tentang cara kerja webpack.
Silakan berkontribusi contoh untuk membantu komunitas.
Di bawah ini adalah contoh cara menambahkan dukungan SVGR ke buku cerita dengan addon ini. Contoh lengkap dapat ditemukan di sini.
// .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
}
} Buku cerita menangani sebagian besar konfigurasi naskah, tetapi addon ini menambahkan dukungan tambahan untuk dukungan Next.js untuk impor absolut dan alias jalur modul. Singkatnya, ia memperhitungkan baseurl dan jalur tsconfig.json Anda. Dengan demikian, tsconfig.json seperti yang di bawah ini akan bekerja di luar kotak.
{
"compilerOptions" : {
"baseUrl" : " . " ,
"paths" : {
"@/components/*" : [ " components/* " ]
}
}
} Saat ini satu -satunya format konfigurasi yang didukung untuk Next.js yang didukung plugin ini adalah versi CommonJS dari konfigurasi (yaitu next.config.js ). Ini sebagian besar karena saya belum tahu bagaimana membutuhkan file .mjs dari addon buku cerita (yang terikat pada modul CommonJS sejauh yang saya tahu sekarang). Jika Anda dapat membantu, saya akan senang jika Anda dapat berkontribusi pada diskusi ini untuk mendapatkan dukungan untuk versi .mjs jika dukungan tersebut bahkan mungkin.
Jika Anda menggunakan YARN V2 atau V3, Anda dapat mengalami masalah di mana buku cerita tidak dapat menyelesaikan style-loader atau css-loader . Misalnya, Anda mungkin mendapatkan kesalahan seperti:
Module not found: Error: Can't resolve 'css-loader'
Module not found: Error: Can't resolve 'style-loader'
Ini karena versi -versi benang itu memiliki aturan resolusi paket yang berbeda dari benang v1.x. Jika ini masalahnya untuk Anda, cukup instal paket secara langsung.
Pastikan Anda memperlakukan impor gambar dengan cara yang sama seperti Anda memperlakukannya saat menggunakan gambar berikutnya dalam pengembangan normal.
Sebelum storybook-addon-next , Impor Gambar baru saja mengimpor jalur mentah ke gambar (misalnya 'static/media/stories/assets/plugin.svg' ). Saat menggunakan storybook-addon-next Impor Impor bekerja dengan "Next.js Way" yang berarti bahwa kita sekarang mendapatkan objek ketika kita mengimpor gambar. Misalnya:
{
"src" : " static/media/stories/assets/plugin.svg " ,
"height" : 48 ,
"width" : 48 ,
"blurDataURL" : " static/media/stories/assets/plugin.svg "
}Oleh karena itu, jika sesuatu dalam buku cerita tidak menunjukkan gambar dengan benar, pastikan Anda mengharapkan objek akan dikembalikan dari impor, bukan hanya jalur aset.
Lihat gambar lokal untuk detail lebih lanjut tentang bagaimana Next.js memperlakukan impor gambar statis.
Saat ini menggunakan next.config.mjs tidak didukung oleh addon ini. Lihat selanjutnya.config.js untuk lebih jelasnya. Saat ini, diperlukan Anda untuk menggunakan ekstensi .js sebagai gantinya. Jangan ragu untuk membantu diskusi ini untuk mendapatkan ini didukung.
Anda mungkin mendapatkan ini jika Anda menggunakan benang V2 atau V3. Lihat Catatan untuk Pengguna YARN V2 dan V3 untuk lebih jelasnya.
Saya terbuka untuk diskusi. Jangan ragu untuk membuka masalah.
Apakah dokumentasi ini tidak cukup untuk Anda?
Apakah itu membingungkan?
Apakah itu ... berani saya katakan ... tidak akurat?
Jika salah satu dari hal di atas menggambarkan perasaan Anda tentang dokumentasi ini. Jangan ragu untuk membuka masalah.
