Memulai perpustakaan komponen React dan TypeScript

Sebagian besar pekerjaan saya, saya menulis backend, tetapi beberapa hari yang lalu ada tugas untuk memulai perpustakaan komponen pada React. Beberapa tahun yang lalu, ketika versi Bereaksi adalah sekecil pengalaman saya dalam pengembangan front-end, saya sudah mengambil pendekatan untuk proyektil dan ternyata dengan kikuk dan kikuk. Dengan mempertimbangkan kematangan ekosistem Bereaksi saat ini dan pengalaman saya yang berkembang, saya terinspirasi kali ini untuk melakukan semuanya dengan baik dan nyaman. Sebagai hasilnya, saya memiliki blank untuk perpustakaan masa depan, dan agar tidak melupakan apa pun dan mengumpulkan semuanya di satu tempat, artikel lembar contekan ini ditulis, yang juga akan membantu mereka yang tidak tahu harus mulai dari mana. Mari kita lihat apa yang saya lakukan.

TL / DR: Kode untuk pustaka siap-pakai dapat dilihat di github

Masalahnya dapat didekati dari dua sisi:

1. Temukan starter-kit, boilerplate atau generator cli yang sudah jadi
2. Kumpulkan semuanya sendiri

Metode pertama baik untuk memulai dengan cepat, ketika Anda benar-benar tidak ingin berurusan dengan mengkonfigurasi dan menghubungkan paket-paket yang diperlukan. Juga, opsi ini cocok untuk pemula yang tidak tahu harus mulai dari mana dan apa perbedaan antara perpustakaan dan aplikasi reguler.

Pada awalnya saya pergi dengan cara pertama, tetapi kemudian saya memutuskan untuk memperbarui dependensi dan mempercepat beberapa paket, dan kemudian semua jenis kesalahan dan inkonsistensi dihujani. Akibatnya, ia menyingsingkan lengan bajunya dan melakukan semuanya sendiri. Tapi saya akan menyebutkan generator perpustakaan.

Buat pustaka reaksi

Sebagian besar pengembang yang berurusan dengan React telah mendengar tentang starter aplikasi React yang nyaman yang memungkinkan Anda untuk meminimalkan konfigurasi proyek dan memberikan default yang masuk akal - Create React App (CRA). Pada prinsipnya, ini bisa digunakan untuk perpustakaan ( ada artikel tentang Habré ). Namun, struktur proyek dan pendekatan untuk pengembangan ui-kit sedikit berbeda dari SPA biasa. Kita memerlukan direktori terpisah dengan kode sumber komponen (src), kotak pasir untuk pengembangan dan debugging (contoh), alat dokumentasi dan demonstrasi ("showcase") dan direktori terpisah dengan file yang disiapkan untuk ekspor (dist). Juga, komponen perpustakaan tidak akan ditambahkan ke aplikasi SPA, tetapi akan diekspor melalui file indeks. Memikirkannya, saya pergi mencari dan dengan cepat menemukan paket CRA serupa - Creat React Library (CRL).

CRL, seperti CRA, adalah utilitas CLI yang "mudah digunakan". Dengan menggunakannya, Anda dapat menghasilkan proyek. Ini akan berisi:

• Rollup yang dikonfigurasi untuk membangun modul cjs dan es dan peta sumber dengan dukungan untuk modul css
• babel untuk transpilasi dalam ES5
• Bercanda untuk tes
• KetikScript (TS) sebagai opsi yang ingin kita gunakan

Untuk menghasilkan proyek perpustakaan, kita dapat melakukannya ( npx memungkinkan kita untuk tidak menginstal paket secara global):

npx create-react-library 

Dan sebagai hasil dari utilitas, kami mendapatkan proyek perpustakaan komponen yang dihasilkan dan siap-pakai.

 npx npm-check -u 

tsdx

Terima kasih kepada pengguna StanEgo , yang berbicara tentang alternatif yang sangat baik untuk Buat React Library - tsdx . Cli-utility ini juga mirip dengan CRA dan dalam satu perintah akan menciptakan dasar untuk perpustakaan Anda dengan Rollup, TS, Prettier, husky, Jest dan React yang sudah dikonfigurasi. Dan Bereaksi datang sebagai opsi. Cukup sederhana untuk dilakukan:

 npx tsdx create mytslib 

Dan sebagai hasilnya, versi segar dari paket yang diperlukan akan diinstal dan semua pengaturan dibuat. Dapatkan proyek seperti CRL. Perbedaan utama dari CRL adalah Zero-config. Yaitu, konfigurasi Rollup disembunyikan dari kami di tsdx (sama seperti CRA).

Setelah menjalankan dokumentasi dengan cepat, saya tidak menemukan metode yang disarankan untuk konfigurasi yang lebih baik atau sesuatu seperti eject seperti pada CRA. Setelah melihat masalah proyek, saya menemukan bahwa sejauh ini tidak ada kemungkinan seperti itu . Untuk beberapa proyek, ini bisa menjadi kritis, dalam hal ini Anda harus bekerja sedikit dengan tangan Anda. Jika Anda tidak membutuhkannya, maka tsdx adalah cara yang bagus untuk memulai dengan cepat.

Kendalikan ke tangan kita sendiri

Tetapi bagaimana jika Anda pergi ke jalan kedua dan mengumpulkan semuanya sendiri? Jadi, mari kita mulai dari awal. Jalankan npm init dan hasilkan package.json untuk pustaka. Tambahkan beberapa informasi tentang paket kami di sana. Sebagai contoh, kami menulis versi minimum untuk node dan npm di bidang engines . File yang dikumpulkan dan diekspor akan ditempatkan di direktori dist . Kami menunjukkan ini di bidang files . Kami membuat pustaka komponen reaksi, jadi kami bergantung pada pengguna untuk memiliki paket yang diperlukan - kami peerDependencies dalam bidang peerDependencies versi minimum versi react dan react-dom .

Sekarang instal paket react dan react-dom dan tipe yang diperlukan (karena kita akan melihat komponen pada TypeScript) sebagai devDependencies (seperti semua paket di artikel ini):

 npm install --save-dev react react-dom @types/react @types/react-dom 

Pasang TypeScript:

 npm install --save-dev typescript 

Mari kita buat file konfigurasi untuk kode utama dan tes: tsconfig.json dan tsconfig.test.json . target kami akan di es5 , kami akan menghasilkan sourceMap , dll. Daftar lengkap opsi yang memungkinkan dan artinya dapat ditemukan dalam dokumentasi . Jangan lupa untuk include direktori sumber di dalam include , dan tambahkan node_modules dan direktori dist dalam exclude . Di package.json kami mengindikasikan di bidang typings tempat untuk mendapatkan tipe untuk pustaka kami - dist/index .

Buat direktori src untuk komponen sumber perpustakaan. Tambahkan segala macam hal kecil, seperti .gitignore , .editorconfig , file dengan lisensi dan README.md .

Rollup

Kami akan menggunakan Rollup untuk perakitan, seperti yang disarankan oleh CRL. Paket dan konfigurasi yang diperlukan, saya juga memata-matai CRL. Secara umum, saya mendengar pendapat bahwa Rollup baik untuk perpustakaan, dan Webpack untuk aplikasi. Namun, saya tidak mengkonfigurasi Webpack (apa yang CRA lakukan untuk saya), tetapi Rollup benar-benar bagus, sederhana dan indah.

Pasang:

 npm install --save-dev rollup rollup-plugin-babel rollup-plugin-commonjs rollup-plugin-node-resolve rollup-plugin-peer-deps-external rollup-plugin-postcss rollup-plugin-typescript2 rollup-plugin-url @svgr/rollup 

Di package.json tambahkan bidang dengan distribusi kumpulan pustaka yang dikumpulkan, seperti yang disarankan rollup kepada kami - pkg.module :

  "main": "dist/index.js", "module": "dist/index.es.js", "jsnext:main": "dist/index.es.js" 

 import typescript from 'rollup-plugin-typescript2'; import commonjs from 'rollup-plugin-commonjs'; import external from 'rollup-plugin-peer-deps-external'; import postcss from 'rollup-plugin-postcss'; import resolve from 'rollup-plugin-node-resolve'; import url from 'rollup-plugin-url'; import svgr from '@svgr/rollup'; import pkg from './package.json'; export default { input: 'src/index.tsx', output: [ { file: pkg.main, format: 'cjs', exports: 'named', sourcemap: true }, { file: pkg.module, format: 'es', exports: 'named', sourcemap: true } ], plugins: [ external(), postcss({ modules: false, extract: true, minimize: true, sourceMap: true }), url(), svgr(), resolve(), typescript({ rollupCommonJSResolveHack: true, clean: true }), commonjs() ] }; 

Konfigurasi adalah file js, atau lebih tepatnya objek yang diekspor. Di bidang input , tentukan file tempat ekspor untuk perpustakaan kami terdaftar. output - menggambarkan harapan kami pada output - di mana modul untuk dikompilasi dalam format dan di mana meletakkannya.

Tambahkan perintah di bidang scripts package.json untuk membangun ( "build": "rollup -c" ) dan mulai perakitan dalam mode-menonton selama pengembangan ( "start": "rollup -c -w && npm run prettier-watch" ) .

Komponen pertama dan ekspor file

Sekarang kita akan menulis komponen reaksi paling sederhana untuk memeriksa cara kerja perakitan kami. Setiap komponen di pustaka akan ditempatkan di direktori terpisah di direktori induk - src/components/ExampleComponent . Direktori ini akan berisi semua file yang terkait dengan komponen - tsx , css , test.tsx dan sebagainya.
Mari kita membuat beberapa file gaya untuk komponen dan file tsx dari komponen itu sendiri.

 /** * @class ExampleComponent */ import * as React from 'react'; import './ExampleComponent.css'; export interface Props { /** * Simple text prop **/ text: string; } /** My First component */ export class ExampleComponent extends React.Component<Props> { render() { const { text } = this.props; return ( <div className="test"> Example Component: {text} <p>Coool!</p> </div> ); } } export default ExampleComponent; 

Juga di src Anda perlu membuat file dengan tipe yang umum untuk perpustakaan, di mana suatu tipe akan dideklarasikan untuk css dan svg (diintip di CRL).

 /** * Default CSS definition for typescript, * will be overridden with file-specific definitions by rollup */ declare module '*.css' { const content: { [className: string]: string }; export default content; } interface SvgrComponent extends React.FunctionComponent<React.SVGAttributes<SVGElement>> {} declare module '*.svg' { const svgUrl: string; const svgComponent: SvgrComponent; export default svgUrl; export { svgComponent as ReactComponent }; } 

Semua komponen dan css yang diekspor harus ditentukan dalam file ekspor. Kami memilikinya - src/index.tsx . Jika beberapa css tidak digunakan dalam proyek dan tidak terdaftar sebagai bagian dari yang diimpor ke src/index.tsx , maka akan dibuang dari majelis, yang baik-baik saja.

 import { ExampleComponent, Props } from './ExampleComponent'; import './export.css'; export { ExampleComponent, Props }; 

Sekarang Anda dapat mencoba membangun pustaka - npm run build . Sebagai hasilnya, rollup memulai dan mengumpulkan pustaka kita menjadi bundel, yang akan kita temukan di direktori dist .

Selanjutnya, kami menambahkan beberapa alat untuk meningkatkan kualitas proses pengembangan kami dan hasilnya.

Lupa pemformatan kode dengan Prettier

Saya benci dalam review kode untuk menunjukkan format yang ceroboh atau tidak standar untuk sebuah proyek, dan bahkan lebih memperdebatkannya. Kelemahan seperti itu secara alami harus diperbaiki, tetapi pengembang harus fokus pada apa dan bagaimana kode dilakukan, bukan pada tampilannya. Perbaikan ini adalah kandidat pertama untuk otomatisasi. Ada paket bagus untuk tugas ini - lebih cantik . Pasang itu:

 npm install --save-dev prettier 

Tambahkan konfigurasi untuk sedikit perbaikan aturan pemformatan.

 { "tabWidth": 3, "singleQuote": true, "jsxBracketSameLine": true, "arrowParens": "always", "printWidth": 100, "semi": true, "bracketSpacing": true } 

Anda dapat melihat arti dari aturan yang tersedia di dokumentasi . WebStrom setelah membuat file konfigurasi itu sendiri akan menyarankan menggunakan prettier ketika mulai memformat melalui IDE. Untuk mencegah pemformatan menghabiskan waktu, tambahkan /node_modules dan /dist ke pengecualian menggunakan file .prettierignore (formatnya mirip dengan .gitignore ). Sekarang Anda dapat menjalankan prettier dengan menerapkan aturan pemformatan ke kode sumber:

 prettier --write "**/*" 

Agar tidak menjalankan perintah secara eksplisit setiap kali dengan tangan Anda dan untuk memastikan bahwa kode dari pengembang proyek lainnya juga akan diformat prettier , tambahkan proses yang prettier pada precommit-hook untuk file yang ditandai sebagai staged (via git add ). Untuk itu, kita perlu dua alat. Pertama, hasky , bertanggung jawab untuk menjalankan perintah apa pun sebelum melakukan, mendorong, dll. Dan kedua, ini adalah lint-bertahap , yang dapat menjalankan berbagai linter pada file staged . Kita hanya perlu menjalankan satu baris untuk mengirimkan paket-paket ini dan menambahkan perintah peluncuran ke package.json :

 npx mrm lint-staged 

Kami tidak bisa menunggu untuk memformat sebelum melakukan, tetapi pastikan bahwa prettier terus bekerja pada file yang dimodifikasi dalam proses pekerjaan kami. Ya, kami membutuhkan paket lain - onchange . Ini memungkinkan Anda untuk memantau perubahan pada file dalam proyek dan segera menjalankan perintah yang diperlukan untuk mereka. Pasang:

 npm install --save-dev --save-exact onchange 

Kemudian kita menambahkan perintah bidang scripts di package.json :

 "prettier-watch": "onchange 'src/**/*' -- prettier --write {{changed}}" 

Mengenai hal ini, semua perselisihan tentang pemformatan dalam proyek dapat dianggap ditutup.

Menghindari Kesalahan dengan ESLint

ESLint telah lama menjadi standar dan dapat ditemukan di hampir semua proyek js dan ts. Dia akan membantu kita juga. Dalam konfigurasi ESLint, saya percaya CRA, jadi ambil saja paket yang diperlukan dari CRA dan colokkan ke pustaka kami. Selain itu, tambahkan konfigurasi untuk TS dan prettier (untuk menghindari konflik antara ESLint dan prettier ):

 npm install --save-dev eslint eslint-config-react-app eslint-loader eslint-plugin-flowtype eslint-plugin-import eslint-plugin-jsx-a11y eslint-plugin-react eslint-plugin-react-hooks @typescript-eslint/eslint-plugin @typescript-eslint/parser babel-eslint eslint-config-prettier eslint-plugin-prettier 

ESLint menggunakan file konfigurasi.

 { "extends": [ "plugin:@typescript-eslint/recommended", "react-app", "prettier", "prettier/@typescript-eslint" ], "plugins": [ "@typescript-eslint", "react" ], "rules": { "@typescript-eslint/no-empty-interface": "off", "@typescript-eslint/explicit-function-return-type": "off", "@typescript-eslint/explicit-member-accessibility": "off" } } 

Tambahkan perintah lint - eslint src/**/* --ext .ts,.tsx --fix ke bidang scripts dari package.json . Sekarang Anda dapat menjalankan eslint melalui npm run lint .

Menguji dengan Jest

Untuk menulis unit test untuk komponen pustaka, instal dan konfigurasikan Jest , pustaka pengujian dari facebook. Namun sejak itu kita mengkompilasi TS bukan melalui babel 7, tetapi melalui tsc, maka kita perlu menginstal paket ts-jest juga:

 npm install --save-dev jest ts-jest @types/jest 

Agar lelucon menerima impor css atau file lain dengan benar, Anda harus menggantinya dengan mokami. Buat direktori __mocks__ dan buat dua file di sana.
styleMock.ts :

 module.exports = {}; 

fileMock.ts :

 module.exports = 'test-file-stub'; 

Sekarang buat konfigurasi gurauan.

 module.exports = { preset: 'ts-jest', testEnvironment: 'node', moduleNameMapper: { '\\.(css|less|sass|scss)$': '<rootDir>/__mocks__/styleMock.ts', '\\.(gif|ttf|eot|svg)$': '<rootDir>/__mocks__/fileMock.ts' } }; 

Kami akan menulis tes paling sederhana untuk ExampleComponent kami di direktori-nya.

 import { ExampleComponent } from './ExampleComponent'; describe('ExampleComponent', () => { it('is truthy', () => { expect(ExampleComponent).toBeTruthy(); }); }); 

Tambahkan test - npm run lint && jest perintah npm run lint && jest ke bidang scripts package.json . Untuk keandalan, kami juga akan menggerakkan linter. Sekarang Anda dapat menjalankan tes kami dan memastikan mereka lulus - npm run test . Dan agar tes tidak jatuh ke dist selama perakitan, tambahkan bidang exclude di plugin konfigurasi Rollup untuk exclude - ['src/**/*.test.(tsx|ts)'] . Tentukan tes yang berjalan dalam husky pre-commit hook sebelum menjalankan lint-staged - "pre-commit": "npm run test && lint-staged" .

Merancang, mendokumentasikan, dan mengagumi komponen dengan Storybook

Setiap perpustakaan membutuhkan dokumentasi yang baik untuk penggunaannya yang sukses dan produktif. Adapun perpustakaan komponen antarmuka, tidak hanya saya ingin membaca tentang mereka, tetapi juga untuk melihat tampilannya, dan yang terbaik adalah menyentuh dan mengubahnya. Untuk mendukung Daftar Keinginan tersebut, ada beberapa solusi. Saya dulu menggunakan Styleguidist . Paket ini memungkinkan Anda untuk menulis dokumentasi dalam format penurunan harga, serta menyisipkan contoh komponen Bereaksi yang dijelaskan di dalamnya. Selanjutnya, dokumentasi dikumpulkan dan darinya diperoleh katalog situs-showcase, di mana Anda dapat menemukan komponen, membaca dokumentasi tentangnya, mencari tahu tentang parameternya, dan juga menyodokkan tongkat ke dalamnya.

Namun, kali ini saya memutuskan untuk melihat lebih dekat kompetitornya - Storybook . Saat ini sepertinya lebih kuat dengan sistem plugin-nya. Selain itu, ia terus berkembang, memiliki komunitas besar, dan akan segera mulai membuat halaman dokumentasinya menggunakan file penurunan harga. Keuntungan lain dari Storybook adalah itu adalah kotak pasir - lingkungan untuk pengembangan komponen yang terisolasi. Ini berarti bahwa kita tidak memerlukan aplikasi sampel lengkap untuk pengembangan komponen (seperti yang disarankan CRL). Dalam buku cerita kami menulis stories - file ts di mana kami mentransfer komponen kami dengan beberapa props input ke fungsi khusus (lebih baik untuk melihat kode untuk membuatnya lebih jelas). Akibatnya, aplikasi showcase dikumpulkan dari stories - stories ini.

Jalankan skrip yang menginisialisasi buku cerita:

 npx -p @storybook/cli sb init 

Sekarang berteman dengan TS. Untuk melakukan ini, kita memerlukan beberapa paket lagi, dan pada saat yang sama kita akan menambahkan beberapa add-on yang bermanfaat:

 npm install --save-dev awesome-typescript-loader @types/storybook__react @storybook/addon-info react-docgen-typescript-loader @storybook/addon-actions @storybook/addon-knobs @types/storybook__addon-info @types/storybook__addon-knobs webpack-blocks 

Script membuat direktori dengan konfigurasi storybook - .storybook dan contoh direktori yang kami hapus dengan kejam. Dan di direktori konfigurasi kita mengubah addons ekstensi dan config ke ts . Kami menambahkan addons ke file addons.ts :

 import '@storybook/addon-actions/register'; import '@storybook/addon-links/register'; import '@storybook/addon-knobs/register'; 

Sekarang, Anda perlu membantu buku cerita menggunakan konfigurasi webpack di direktori .storybook .

 module.exports = ({ config }) => { config.module.rules.push({ test: /\.(ts|tsx)$/, use: [ { loader: require.resolve('awesome-typescript-loader') }, // Optional { loader: require.resolve('react-docgen-typescript-loader') } ] }); config.resolve.extensions.push('.ts', '.tsx'); return config; }; 

Mari kita sedikit mengubah config.ts config, menambahkan dekorator untuk menghubungkan add-on ke semua cerita kita.

 import { configure } from '@storybook/react'; import { addDecorator } from '@storybook/react'; import { withInfo } from '@storybook/addon-info'; import { withKnobs } from '@storybook/addon-knobs'; // automatically import all files ending in *.stories.tsx const req = require.context('../src', true, /\.stories\.tsx$/); function loadStories() { req.keys().forEach(req); } configure(loadStories, module); addDecorator(withInfo); addDecorator(withKnobs); 

Kami akan menulis story pertama kami di direktori komponen ExampleComponent

 import * as React from 'react'; import { storiesOf } from '@storybook/react'; import { ExampleComponent } from './ExampleComponent'; import { text } from '@storybook/addon-knobs/react'; const stories = storiesOf('ExampleComponent', module); stories.add('ExampleComponent', () => <ExampleComponent text={text('text', 'Some text')} />, { info: { inline: true }, text: ` ### Notes Simple example component ### Usage ~~~js <ExampleComponent text="Some text" /> ~~~ ` }); 

Sekarang perhatikan bahwa skrip inisialisasi buku cerita menambahkan perintah buku cerita ke package.json kami. Gunakan untuk npm run storybook . Storybook akan berkumpul dan berjalan di http://localhost:6006 . Jangan lupa menambahkan pengecualian untuk modul typescript dalam Rollup config - 'src/**/*.stories.tsx' .

Kami sedang berkembang

Jadi, setelah mengelilingi diri Anda dengan banyak alat yang praktis dan mempersiapkannya untuk bekerja, Anda dapat mulai mengembangkan komponen baru. Setiap komponen akan ditempatkan di direktori dalam src/components dengan nama komponen. Ini akan berisi semua file yang terkait dengannya - css, komponen itu sendiri dalam file tsx, tes, cerita. Kami memulai buku cerita, membuat cerita untuk komponen, dan di sana kami menulis dokumentasi untuknya. Kami membuat tes dan tes. Ekspor-impor komponen jadi ditulis dalam index.ts .

Selain itu, Anda dapat masuk ke npm dan menerbitkan perpustakaan Anda sebagai paket npm baru. Dan Anda dapat menghubungkannya langsung dari repositori git dari master dan cabang lainnya. Misalnya, untuk benda kerja saya, Anda dapat melakukan:

 npm i -s git+https://github.com/jmorozov/react-library-example.git 

Sehingga dalam aplikasi konsumen perpustakaan di direktori node_modules hanya ada isi direktori dist dalam keadaan berkumpul, Anda perlu menambahkan perintah "prepare": "npm run build" ke bidang scripts .

Juga, terima kasih kepada TS, penyelesaian otomatis di IDE akan berfungsi.

Untuk meringkas

Pada pertengahan 2019, Anda dapat dengan cepat mulai mengembangkan pustaka komponen Anda pada React dan TypeScript, menggunakan alat pengembangan yang praktis. Hasil ini dapat dicapai baik dengan bantuan utilitas otomatis, dan dalam mode manual. Cara kedua lebih disukai jika Anda membutuhkan paket saat ini dan lebih banyak kontrol. Hal utama adalah mengetahui di mana harus menggali, dan dengan bantuan contoh dalam artikel ini, saya harap ini menjadi lebih mudah.

Anda juga dapat mengambil benda kerja yang dihasilkan di sini .

Di antara hal-hal lain, saya tidak berpura-pura menjadi kebenaran tertinggi dan, secara umum, saya terlibat dalam front-end sejauh. Anda dapat memilih paket alternatif dan opsi konfigurasi dan juga berhasil membuat pustaka komponen Anda. Saya akan senang jika Anda membagikan resep Anda di komentar. Selamat coding!