storybook addon next
v1.8.0
تم إهمال هذا الملحق لصالح @Storybook/NextJS وهو الملحق الرسمي Storybook لدعم ميزات Next.js في Storybook. وهو يدعم كل شيء storybook-addon-next أكثر من ذلك بكثير! حتى أنني عملت على تطوير هذا معهم ، لذا يجب أن تكون في أيد أمينة.
استشر مستندات الترحيل للحصول على تفاصيل حول كيفية الترحيل.
؟ لا يوجد دعم للتكوين لـ NEXT.JS : تعبت من كتابة وتصحيح تكوين WebPack؟ ما يدعمه next.js خارج الصندوق ، هذا الملحق يجعله ممكنًا في كتاب القصص
مكون صورة Next.js (دعم جزئي)
توجيه next.js
Sass/SCSS
وحدات CSS/SASS/SCSS
تصميم JSX
postcss
الواردات المطلقة
تكوين وقت التشغيل
تكوين webpack مخصص
TypeScript
.mjs next.config.js next.config.mjs التالي .jsلتشغيل أي مثال ، قم أولاً ببناء الملحق عن طريق تشغيل
yarn buildفي جذر هذا الريبو.
تثبيت storybook-addon-next باستخدام yarn :
yarn add --dev storybook-addon-next أو npm :
npm install --save-dev storybook-addon-next // .storybook/main.js
module . exports = {
// other config ommited for brevity
addons : [
// ...
'storybook-addon-next'
// ...
]
}؟ هذا كل شيء! يجب أن تعمل الميزات المدعومة خارج الصندوق.
راجع الوثائق لمزيد من التفاصيل حول كيفية عمل الميزات المدعومة في هذا الملحق.
إذا كان هناك شيء لا يعمل كما تتوقع ، فلا تتردد في فتح مشكلة.
يمكن تمرير هذا الملحق كائن خيارات للتكوين الإضافي إذا لزم الأمر.
على سبيل المثال:
// .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 : المسار المطلق إلى next.config.js من الصعب الحصول على الصورة التالية/الصورة مع القصة. يتيح لك هذا الملحق استخدام مكون Image Next.js بدون تكوين!
نظرًا لأن مكون الصورة يحتوي على ميزات ، مثل تحسين الصور ، تم تكوينها بواسطة الخيارات التي تتطلب قراءة ملف Config Next.js بواسطة الإطار ولا توجد وظيفة عامة تتعرض بواسطة Next.js لحلها وتلك الخيارات ، لا يمكن دعم هذه الميزات بشكل ثابت.
إذا كنت تريد أن ترى هذا مدعومًا بشكل أفضل ، فلا تتردد في المساهمة في المناقشة على جانب Next.js أو المناقشة على جانبنا
الصور المحلية تعمل بشكل جيد مع هذا الملحق! ضع في اعتبارك أنه تمت إضافة هذه الميزة فقط في 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 >
</ >
)
} الصور عن بعد تعمل أيضًا بشكل جيد!
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 >
</ >
)
} كل Image Next.js غير محسوبة تلقائيًا بالنسبة لك.
إذا تم استخدام العنصر النائب = "Blur" ، فإن Blurdataurl المستخدم هو SRC للصورة (وبالتالي تعطيل العنصر النائب بشكل فعال).
شاهد هذه المشكلة لمزيد من النقاش حول كيفية معالجة Image Next.js لقصة القصص.
هذا التنسيق غير مدعوم من هذا الملحق حتى الآن. لا تتردد في فتح مشكلة إذا كان هذا شيء تريد رؤيته.
يعتمد هذا الحل اعتمادًا كبيرًا على القصة القصيرة-المدولة-الشكر الشديد لـ lifeiscontent لتوفير حل جيد يمكن لهذا الملحق أن يعمل عليه.
يتم توجيه جهاز التوجيه الخاص بـ Next.js تلقائيًا بحيث يتم تلقائيًا عند تفاعل جهاز التوجيه ، يتم تسجيل جميع تفاعلاته تلقائيًا إلى علامة تبويب إجراءات القصص القصيرة إذا كان لديك Actions Adply Addon.
يمكن إجراء التجاوزات لكل قصة عن طريق إضافة خاصية nextRouter على معلمات القصة. سوف يدمج الملحق بشكل ضحل كل ما تضعه هنا في جهاز التوجيه.
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"
}
}
}انظر هذا المثال للرجوع.
يمكن تعيين الافتراضات العالمية في معاينة. js وسيتم دمجها ضحلة مع جهاز التوجيه الافتراضي.
export const parameters = {
nextRouter : {
path : '/some-default-path' ,
asPath : '/some-default-path' ,
query : { }
}
}انظر هذا المثال للرجوع.
القيم الافتراضية على جهاز التوجيه البغيض هي كما يلي (انظر Globals لمزيد من التفاصيل حول كيفية عمل 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
} إذا قمت بتجاوز وظيفة ما ، تفقد تكامل علامة تبويب الإجراء التلقائي وعليك أن تنشئها بنفسك.
export const parameters = {
nextRouter : {
push ( ) {
// we lose the default implementation that logs the action into the action tab
}
}
} إن القيام بذلك بنفسك يبدو مثل هذا (تأكد من تثبيت حزمة @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 )
}
}
}يتم دعم أوراق أنماط SASS/SCSS العالمية دون أي تكوين إضافي أيضًا. فقط استيرادها إلى معاينة
import '../styles/globals.scss' سيتضمن ذلك تلقائيًا أيًا من تكوينات SASS المخصصة في ملف next.config.js .
في الوقت الحالي ، تم دعم امتداد
.jsفقط لـ Next.js ، وليس.mjs. انظر 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 يدعم وحدات CSS خارج المربع بحيث يدعمها هذا الملحق أيضًا.
// 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 >
)
}تم تصميم CSS في حل CSS لـ NEXT.JS-jsx ، وهذا الملحق يدعم ذلك خارج المربع أيضًا ، 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 HelloWorldيمكنك استخدام تكوين بابل الخاص بك أيضًا. هذا مثال على كيفية تخصيص jsx styled-jsx.
// .babelrc or whatever config file you use
{
"presets" : [
[
" next/babel " ,
{
"styled-jsx" : {
"plugins" : [ " @styled-jsx/plugin-sass " ]
}
}
]
]
}إذا كنت تستخدم monorepo ، فقد تحتاج إلى إضافة تكوين Babel بنفسك إلى مشروع Storybook الخاص بك. ما عليك سوى إضافة تكوين بابل إلى مشروع قصة القصص الخاصة بك مع المحتويات التالية للبدء.
{
"presets" : [ " next/babel " ]
}يتيح لك next.js تخصيص تكوين postcss. وبالتالي ، سيقوم هذا الملحق تلقائيًا بمعالجة تكوين postCSS لك.
هذا يسمح بأشياء رائعة مثل Zero Config Tailwindcss! انظر مثال مع Tailwindcss للرجوع إليه! إنه استنساخ من مثال Tailwindcss الخاص بـ next.js مع القصة وهذا الملحق.
مع السلامة ../ ! تعمل الواردات المطلقة من دليل الجذر على ما يرام مع هذا الملحق.
// 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 تكوين وقت التشغيل الذي يتيح لك استيراد وظيفة getConfig المفيدة للحصول على تكوين معين محدد في ملف next.config.js الخاص بك في وقت التشغيل.
في سياق Storybook مع هذا الملحق ، يمكنك توقع أن تعمل ميزة تكوين وقت التشغيل الخاصة بـ JEL.JS بشكل جيد.
ملاحظة ، نظرًا لأن Storybook لا يقدم الخادم مكوناتك ، فإن مكوناتك ستشاهد فقط ما يرونه عادة على جانب العميل (أي لن يروا serverRuntimeConfig ولكنهم سيرون publicRuntimeConfig ).
على سبيل المثال ، ضع في اعتبارك تكوين التالي. js:
// next.config.js
module . exports = {
serverRuntimeConfig : {
mySecret : 'secret' ,
secondSecret : process . env . SECOND_SECRET // Pass through env variables
} ,
publicRuntimeConfig : {
staticFolder : '/static'
}
} ستعود المكالمات إلى getConfig إلى الكائن التالي عند استدعاؤه داخل Storybook:
{
"serverRuntimeConfig" : {},
"publicRuntimeConfig" : {
"staticFolder" : " /static "
}
}يأتي Next.js مع الكثير من الأشياء مجانًا خارج المربع مثل دعم Sass ، ولكن في بعض الأحيان نضيف تعديلات تكوين WebPack مخصصة إلى Next.js. يعتني هذا الملحق بمعظم تعديلات WebPack التي ترغب في إضافتها. إذا دعم Next.js ميزة خارج المربع ، فإن هذا الملحق سيجعل هذه الميزة تعمل خارج الصندوق في Storybook. إذا لم يدعم next.js شيئًا ما خارج المربع ، ولكنه يسهل تكوينه ، فإن هذا الملحق سيفعل نفس الشيء لهذا الشيء لقصة القصص. إذا وجدت شيئًا ما زلت بحاجة إلى تكوين WebPack للحصول على ميزة Next.js للعمل في Storybook بعد إضافة هذا الملحق ، فمن المحتمل أن يكون هذا خطأً ويرجى أن تتردد في فتح مشكلة.
يجب إجراء أي تعديلات على حزمة الويب المطلوبة للقصص في .storybook/main.js وفقًا لمستندات Storybook.
ملاحظة: ليست كل تعديلات WebPack نسخ/لصق بين next.config.js و .storybook/main.js . يوصى بإجراء البحث الخاص بك حول كيفية جعل تعديلك بشكل صحيح على تكوين WebBack الخاص بقصة Storybook وكيفية عمل WebPack.
لا تتردد في المساهمة في مثال لمساعدة المجتمع.
فيما يلي مثال على كيفية إضافة دعم SVGR إلى Storybook مع هذا الملحق. يمكن العثور على المثال الكامل هنا.
// .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 مع معظم تكوينات TypeScript ، لكن هذا Addon يضيف دعمًا إضافيًا لدعم Next.js للواردات المطلقة ومسار المسار النمطية. باختصار ، يأخذ في الاعتبار مسارات ومسارات tsconfig.json الخاصة بك. وبالتالي ، فإن tsconfig.json مثل واحد أدناه سوف يعمل خارج الصندوق.
{
"compilerOptions" : {
"baseUrl" : " . " ,
"paths" : {
"@/components/*" : [ " components/* " ]
}
}
} في الوقت الحالي ، فإن تنسيق التكوين المدعوم الوحيد لـ next.js الذي يدعمه هذا المكون الإضافي هو إصدار CommonJS من التكوين (أي next.config.js ). هذا في الغالب لأنني لم أحسب كيفية طلب ملف .mjs من ملحق قصص القصة (والذي لا بد أن يكون وحدات CommonJS بقدر ما أعرف الآن). إذا كنت قادرًا على المساعدة ، فأنا أحب ذلك إذا تمكنت من المساهمة في هذه المناقشة للحصول على دعم لإصدار .mjs إذا كان هذا الدعم ممكنًا.
إذا كنت تستخدم Yarn V2 أو V3 ، فيمكنك مواجهة مشكلات حيث لا يمكن لـ Storybook حل style-loader أو css-loader . على سبيل المثال ، قد تحصل على أخطاء مثل:
Module not found: Error: Can't resolve 'css-loader'
Module not found: Error: Can't resolve 'style-loader'
وذلك لأن تلك الإصدارات من الغزل لها قواعد دقة حزمة مختلفة عن الغزل V1.x. إذا كان هذا هو الحال بالنسبة لك ، فما عليك سوى تثبيت الحزمة مباشرة.
تأكد من أنك تتعامل مع واردات الصور بنفس الطريقة التي تعامل بها عند استخدام الصورة التالية في التطوير العادي.
قبل storybook-addon-next ، استوردت واردات الصور المسار الخام إلى الصورة (على سبيل المثال 'static/media/stories/assets/plugin.svg' ). عند استخدام واردات storybook-addon-next تعمل واردات الصور "Next.js" ، مما يعني أننا نحصل الآن على كائن عند استيراد صورة. على سبيل المثال:
{
"src" : " static/media/stories/assets/plugin.svg " ,
"height" : 48 ,
"width" : 48 ,
"blurDataURL" : " static/media/stories/assets/plugin.svg "
}لذلك ، إذا كان هناك شيء ما في Storybook لا يعرض الصورة بشكل صحيح ، فتأكد من توقع إرجاع الكائن من استيراد بدلاً من مسار الأصول فقط.
شاهد الصور المحلية لمزيد من التفاصيل حول كيفية تعامل Next.js مع واردات الصور الثابتة.
في الوقت الحالي next.config.mjs لا يتم دعم هذا الملحق. انظر Next.config.js لمزيد من التفاصيل. في الوقت الحالي ، يجب عليك استخدام ملحق .js بدلاً من ذلك. لا تتردد في المساعدة في هذه المناقشة للحصول على هذا الدعم.
قد تحصل على هذا إذا كنت تستخدم Yarn V2 أو V3. انظر ملاحظات لمستخدمي Yarn V2 و V3 لمزيد من التفاصيل.
أنا منفتح على المناقشة. لا تتردد في فتح مشكلة.
هل كانت هذه الوثائق غير كافية بالنسبة لك؟
هل كانت مربكة؟
هل كان ... يجرؤ على القول ... غير دقيق؟
إذا كان أي مما سبق يصف مشاعرك من هذه الوثائق. لا تتردد في فتح مشكلة.
