These steps should get you up and started for local development setup. Please ensure you've NodeJS and Yarn installed on your machine before proceeding.
-
cd
intopackages/blade
-
Install dependencies:
yarn
-
Run storybook for web:
yarn start:web
-
That's it! You can access storybook on http://localhost:9009
If you're contributing to React Native parts, you can follow the following setup.
You can skip it if you're contributing to web only component. Our Component Status Page in Documentation mentions which components are react native supported and which are web only
-
Get a tea, coffee or your favorite drink, you'll need it 😸
-
Install
brew
if you don't have it installed -
Install watchman:
brew install watchman
-
Install Xcode.
[!Note]
Sometimes it can take a very long time for Xcode to install. Check here for troubleshooting.
-
Install an iOS 13 simulator in Xcode: Xcode > Preferences > Platforms.
[!Note]
Sometimes this can get stuck or take a very long time. Check here for troubleshooting.
-
Install cocoapods:
sudo gem install cocoapods
-
Install pods. This can be done by running
pod install
in theios/
directory for Intel machine. For M1, things might not work out of box.[!Note]
Follow the note here if you're using M1
-
cd
back topackages/blade
. Start storybook dev-server for ios:yarn start:ios
Tip:
You don't need to build the app everytime (only when you're changing native dependencies), once the app is built you can just start the storybook server and open the app directly on your simulator
-
If the stars aligned correctly, the storybook app should get installed and up and running on the simulator. If not, please refer to the official guide for any deviations.
The storybook can take some time to open after simulator starts. Don't worry, it will start after few minutes (hopefully 🤞).
-
Of course you'll need a fresh cup of tea, coffee or your favorite drink 😸
-
Follow the official guide. Some of the initial steps needed are the same for iOS. Please note the following tips and deviations:
- Use the Android 12 SDK, when you follow the official guide, the default selected SDK is not Android 12
- When you setup the emulator from Android Studio, create a fresh one (delete the one that is created by default). The default one comes with low storage and memory so you'll likely run into
INSTALL_FAILED_INSUFFICIENT_STORAGE
issue. For RAM and virtual memory heap you may use2000
and for storage4000
as values.
Tip
At times, you might run into some weird issues during installation. Sometimes restarting your computer does the trick. You can also
cd
into theandroid
directory and run./gradlew clean
to clean up cache and built files when retrying installation or running the app. -
cd
back topackages/blade
. Start the storybook dev-server for android:yarn start:android
[!Note]
If you already have
yarn start:ios
running, you might have to close it sinceyarn start:android
will try to run react-native server on the same port and fail with port taken error.If you want to run both, android and ios at the same time, you can use
yarn start:native
instead.[!Note]
Make sure
$ANDROID_SDK_ROOT
is added before running the above command, you can runecho $ANDROID_SDK_ROOT
in same terminal to confirm. (You can runsource ~/.zshrc
orsource ~/.bash_profile
depending on where you added the variables) -
If the stars aligned correctly, the storybook app should get installed and up and running on the emulator 🎉
[!TIP]
You can use
yarn start:all
command to run storybooks on all platforms like web, android, and ios (better to not use it in development though to avoid stressing your laptop)
We have some base components defined internally such as BaseInput, BaseButton, BaseText which act as a base for multiple exposed components.
E.g.
- Heading, Display, Text all use BaseText internally
- TextInput, PasswordInput, SelectInput all use BaseInput internally
- Majority of our components use BaseBox internally which is a more flexible version of the exposed Box component.
You will see files with .web.tsx
or .native.tsx
syntax. The .web.tsx
files end up in web bundle and .native.tsx
files end up in react native bundle. You can define common logic in normal .tsx
files which can be imported in both web and native files.
Writing Cross-Platform TypeScript In Blade
We have unit tests which you can run by running following commands
cd packages/blade
yarn test:react # web tests
yarn test:react-native # native tests
We also have visual tests that run on every PR. So if your PR changes / breaks a certain component, the diff will show up on chromatic checks of PR
We support writing interaction tests using playwright. You can check example interaction tests of toast at Toast.test.stories.tsx. You can run these tests by visiting the Interaction Tests section in blade documentation E.g. Toast Stacking Interaction Test on Documentation
- Make sure you have ESLint installed and setup on your VSCode. This will guide you and autofix errors to keep the code consistent with this project's guidelines
- Make sure you have VSCode MDX installed on your VSCode. This will help you with linting the markdown files if you're modifying or adding any
mdx
files for documentation purpose.- After installing this plugin navigate to your settings and add
mdx
extension to youreslint
config. Below is how your settings will look after configuringmdx
to work with eslint
// .vscode/settings.json { "editor.codeActionsOnSave": { "source.fixAll.eslint": true }, "eslint.options": { "extensions": [".js", ".jsx", ".md", ".mdx", ".ts", ".tsx"] }, "eslint.validate": [ "markdown", "mdx", "javascript", "javascriptreact", "typescript", "typescriptreact" ] }
- After installing this plugin navigate to your settings and add
-
VSCode auto imports can sometimes mess things up due to import aliases and
.web
/.native
extensions. If something is breaking weirdly after adding / importing a new module this might be related -
Ensure you're not using any
.web
,.native
files directly in respective imports in.web
/.native
modules. For example, if you end up importing a.web
module accidentally in a.native
module, you might see a blank component being rendered or module not found error -
If you forget to import types inside a
.d.ts
file, sometimes TS won't complain and it can throw the typecheck logic in other modules off -
Blade requires "FRAMEWORK" environment variable to be set. Valid values are "REACT" and "REACT_NATIVE". Instead, received: undefined
Issue: This is an issue that happens mostly if you run
yarn android
directly. For some reasonFRAMEWORK
doesn't gets passed to React Native applicationFix: If you come across this issue then you first run
yarn start
and then runyarn android
.