Siirtoopas Storybook 7.0:lle (2023)

Storybook 7 on ensimmäinen merkittävä julkaisumme yli kahteen vuoteen. Paljon on muuttunut tuona aikana, joten tämä on iso asia. Tämä opas on tarkoitettu auttamaan sinuapäivitä Storybook 6.x:stä versioon 7.0onnistuneesti!

Suuria murtuvia muutoksia

Tämän oppaan loppuosa auttaa sinua päivittämään onnistuneesti joko automaattisesti tai manuaalisesti. Mutta ensin, olemme keränneet paljonrikkovia muutoksiaStorybook 7:ssä. Tässä ovat vaikuttavimmat muutokset, joista sinun tulee tietää ennen kuin jatkat:

Jos jokin näistä koskee projektiasi, lue läpitäydelliset siirtymätiedotennen kuin jatkat. Jos jokin näistä uusista vaatimuksista tai muutoksista ei sovi projektiisi, sinun pitäisi luultavasti pysyä Storybook 6.x:n kanssa.

Automaattinen päivitys

Satukirjan päivittäminen:

Tämä tulee:

Päivitä Storybook-riippuvuutesi uusimpaan versioon
Suorita kokoelmaautomaattiset migraatiot, joka tulee:
- Tarkista yleiset päivitystehtävät
- Selitä tarvittavat muutokset linkkien avulla lisätietoihin
- Pyydä hyväksyntää ja suorita sitten tehtävä puolestasi

Voit lisätä Storybookin projektiin, joka ei tällä hetkellä käytä Storybookia:

Tämä tulee:

Selvitä, mitä renderöijää (React, Vue, Angular, Web Components), rakentajaa (Webpack, Vite) tai metakehystä (Next.js, SvelteKit) käytät
Asenna Storybook 7 ja määritä se automaattisesti vastaamaan projektiasetuksia

Manuaaliset siirrot

Yllä olevien automaattisten päivitysten lisäksi voidaan tarvita manuaalisia siirtoja, jotta Storybook 7 toimisi projektissasi. Olemme yrittäneet minimoida tämän luettelon päivittämisen helpottamiseksi. Nämä sisältävät:

Päivitä MDX1 MDX2:ksi
tarinoitatuki on oletusarvoisesti lopetettu

Päivitä MDX1 MDX2:ksi

Storybook 7 käyttää oletusarvoisesti MDX2:ta hahmontamiseenasiakirjoja. Päivitys MDX1:stä MDX2:een ei ole täysin automatisoitu, koska versioiden välillä on paljon muutoksia. Onneksi meillä on muutamia vinkkejä, jotka auttavat tekemään siitä paljon helpompaa.

Tunnista MDX2-virheet automaattisesti CLI-työkalulla

Jos projektisi sisältää MDX-tiedostoja, suorita seuraava komento ennen Storybookin käynnistämistä:

Tämä käy läpi jokaisen nykyisen työhakemiston MDX-tiedoston ja näyttää, missä tiedostoissa on virheitä:

Korjaa MDX2-virheet iteratiivisesti

CLI näyttää vain ensimmäisen virheen tiedostoa kohti, joten sinun on ehkä suoritettava tarkistus iteratiivisesti. Yksi tapa virtaviivaistaa tätä prosessia, jos käytät VS-koodia, on:

AsennaMDX VS -koodin laajennus
Ota käyttöön kokeellinen IntelliSense-tuki MDX-tiedostoille käyttäjäasetuksissasi:"mdx.experimentalLanguageServer": tosi

Tämä näyttää virheet visuaalisesti editorissasi, mikä nopeuttaa asioita huomattavasti. Tältä näyttää useiden tiedostojen virheiden korjaaminen laajennuksen avulla:

MDX1 varavaihtoehtona

Jos et jostain syystä saa MDX2:ta toimimaan, olemme ottaneet käyttöön vanhan MDX1-tuen viimeisenä keinona. MDX1 on vanhentunut ja se on valittavissa, ja suosittelemme, ettei sitä tarvita, ellet todella tarvitse sitä.

MDX1:n käyttäminen:

Asentaa@tarinakirja/mdx1-csfkehittäjäriippuvuudena
LisäälegacyMdx1ominaisuus lippu sinulle.storybook/main.js:

StoriesOf-tuki lopetettiin oletuksena

Jos käytät Storybookin perintöätarinoitaAPI, se ei ole enää oletuksena tuettu Storybook 7:ssä.

Suosittelemme päivittämääntarinoitatarinoitaComponent Story Format (CSF). Voit tehdä sen tutustumalla meidänalla valinnaiset siirtoohjeet.

Jos et voi päivittää CSF:ään tai haluat saada projektisi toimimaan Storybook 7:n kanssa ennen kuin käytät aikaa päivitykseen, voit kieltäytyä tarinoiden lataamisesta pyynnöstä. Tällä vanhalla tilalla on useita suorituskykyvaikutuksia, mutta se on kätevä ratkaisu.

Poista käytöstä lisäämälläStoreStoreV7ominaisuus lippu sisään.storybook/main.js:

Lisätietoja tästä muutoksesta on osoitteessamuuttomuistiinpanot.

Ongelmien karttoittaminen

Automaattisen päivityksen pitäisi saada Storybookisi toimivaan tilaan. Jos kohtaat virheen Storybookissa päivityksen jälkeen, toimi seuraavasti:

Jos olet juoksemassasatukirjakanssakehittäjä-komentoa, kokeile käyttäärakentaakomento sen sijaan. Joskusrakentaavirheet ovat luettavampia kuinkehittäjävirheitä!
Tarkistaatäydelliset siirtymätiedot, joka sisältää kattavan luettelon huomionarvoisista muutoksista Storybook 7:ssä. Automigrations käsittelee monia näistä jo päivityksen yhteydessä, mutta eivät kaikki. On myös mahdollista, että sinulla on nurkkatapaus, josta emme ole tietoisia.
HaeSatukirjan ongelmat GitHubissa. Jos näet ongelman, on olemassa hyvä mahdollisuus, että myös muut ihmiset ovat sitä mieltä. Jos näin on, äänestä ongelmasta, kokeile kommenteissa kuvattuja kiertotapoja ja kommentoi, jos sinulla on hyödyllistä tietoa.
Jos olemassa olevaa ongelmaa ei ole, voittiedosto yksi, mieluiten jäljennöksen kanssa. Olemme Storybook 7 -ongelmien kärjessä, kun vakautamme julkaisua.
Jos pidät enemmän interaktiivisesta mediasta, kokeile#esijulkaisufoorumillaSatukirja Discord. Meillä on Storybook-ylläpitäjiä ja suuri käyttäjäyhteisö, joiden pitäisi pystyä auttamaan sinua.

Jos haluat tehdä virheenkorjauksen itse, tässä on muutamia hyödyllisiä asioita, joiden avulla voit rajata ongelmaa:

Yritä poistaa kaikki lisäosat, joita ei ole@satukirjanpm nimiavaruus. Yhteisölisäosat, jotka toimivat hyvin 6.x:n kanssa, eivät ehkä ole vielä yhteensopivia 7.0:n kanssa, ja tämä on nopein tapa eristää tämä mahdollisuus. Jos löydät lisäosan, joka on päivitettävä toimimaan Storybook 7:n kanssa, lähetä ongelma lisäosan arkistoon tai, mikä vielä parempaa, PR päivittää se!
Toinen virheenkorjaustekniikka on jakaa Storybookin vanhempiin esijulkaisuversioihin, jotta saadaan selville, mikä julkaisu rikkoi Storybookisi. Oletetaan esimerkiksi, että Storybookin nykyinen esijulkaisu on7.0.0-beta.56, voit asettaa version7.0.0-alfa.0sinunpackage.jsonja asenna uudelleen varmistaaksesi, että se toimii edelleen (alpha.0:n pitäisi olla lähes identtinen6.5.x). Jos se toimii, voit kokeilla7.0.0-beta.0, sitten7.0.0-beta.28ja niin edelleen. Kun olet eristänyt huonon julkaisun, lue se läpiCHANGELOGsisääntuloa ja ehkä syynä on muutos. Jos löydät ongelman, lähetä ongelma tai PR Storybook repoon, niin teemme parhaamme hoitaaksemme sen nopeasti.

Valinnaiset siirrot

Yllä olevien automaattisten ja manuaalisten siirtojen lisäksi on myös valinnaisia siirtoja, joita sinun tulee harkita. Nämä ovat asioita, jotka olemme poistaneet käytöstä Storybook 7:ssä (mutta ne ovat edelleen yhteensopivia taaksepäin), tai parhaita käytäntöjä, joiden pitäisi auttaa sinua olemaan tuottavampi tulevaisuudessa.

Nämä sisältävät:

Päivitä Component Story Format v3:een (CSF3), joka on esimerkkimuodomme uusin iteraatio
Päivitä vanhasta storyOf API:sta Component Story Format -muotoon
Päivitä osoitteesta.stories.mdxtiedostot puhtaaseen MDX- ja Component Story -muotoon
Päivitys Storybook 6 -reseptistä "CSF-tarinat mielivaltaisella MDX:llä"

CSF2:sta CSF3:ksi

Julkaisimme ayksityiskohtainen viesti CSF3:stamukaan lukien kaikki sen edut ja muuttovaiheet.

Jos haluat vain siirtyä siirtoon, tarjoamme avuksesi koodimodin, jonka pitäisi automaattisesti tehdä koodimuutokset puolestasi (muista päivittää glob, jotta se sopii tiedostoihisi):

tarinoita CSF:lle

Storybook 7:n arkkitehtuuri keskittyy suorituskykyyn ja tarvitsee koodia, joka on staattisesti analysoitava. Tästä syystä se ei toimitarinoita. Tarjoamme koodimallin, jonka pitäisi useimmissa tapauksissa automaattisesti tehdä koodimuutokset puolestasi (muista päivittää glob, jotta se sopii tiedostoihisi):

.stories.mdx MDX+CSF:ksi

Storybook 7 tarjoaa siivoojanasiakirjojajoka määrittelee manuaalisen dokumentaation puhtaalla MDX:llä ja tarinat CSF:ssä edellisen sijaan.stories.mdxhybridilähestymistapa, joka on nyt poistettu käytöstä. Voit muuntaa tiedostosi automaattisesti seuraavalla koodimodilla (muista päivittää glob, jotta se sopii tiedostoihisi):

Sinun on myös päivitettävä omasitarinoitaglob in.storybook/main.jssisällyttää uusi luotu.mdxja.stories.jstiedostot, jos se ei jo ole.

HUOMAUTUS:tämä siirto tukee Storybook 6:ta"CSF-tarinat MDX-dokumenteilla"resepti.

Satukirjan 6 resepti "CSF-tarinat mielivaltaisella MDX:llä"

Satukirjassa 6 oli toinen resepti,"CSF-tarinat mielivaltaisella MDX:llä". Tätä reseptiä tuetaan edelleen Storybook 7:ssä, mutta uusi suositus on puhtaampi ja tulevaisuudenkestävämpi. Päivitä manuaalisesti seuraavan esimerkin avulla:

Ennen

Jälkeen

MDX-tiedostosi tulee päivittää viittaamaan CSF-tarinoiden vientiin, mikä on turvallisempaa ja puhtaampaa kuin merkkijonotunnukseen viittaaminen:

Sinun tulee myös poistaa MDX-tuonnit tarinatiedostoistasi:

Lopuksi sinun on lisättävä MDX-tiedostot.storybook/main.jsjotta ne indeksoidaan: