The web3uiKit is aimed at helping developers build web3 dApps fast, delivering a quality DX to our developers plus an inclusive and reliable UX to your end users. Thank you for taking an interest in contributing to what we aim to be the industry standard in web3 UI/UX kits... we need your help.
- a fast and reliable kit that is easy to use for devs (top DX)
- a friendly user experience that has great accessibility (topUX)
- strict typed components to kill those bugs before they happen
- building a community of front end mages who are passion about web3
- finding our next FrontEnd master to join our expanding international team (that could be you)
We have made a battle tested front end web3 stack for the roaring 20s
- React JS: Industry standard, no need to say more
- Typescript: strongly typed props and data means no bugs
- Styled Components: Encapsulated CSS with all the power of SCSS & JS
- Storybook: lets us build quickly in isolation and test props on the fly
- RTL: React Test Library makes testing easy
- Prettier makes our code look nice and helps with Pull Requests
- pnpm is used to get reliable monorepo package management on Mac, PC & Lynx
You want to get started? Follow these 3 simple steps
- Clone the web3uiKit repo https://github.com/web3ui/web3uikit
- Open a terminal window and
cdto the project folder - Run
pnpm installyou may need to install pnpm globally first - Make a new branch, see BRANCH NAMING
- Run
pnpm build - Run
pnpm storybookand there you go, ready to code? - Not sure where to start, lets look at
NewCompwe made it specially for you - Want to create a new component? run
pnpm newto create boilerplate code. - Still stuck? Checkout the onboarding video (bottom of this page)
- You can download nvm to switch between the node versions. Try to be at node version 16. [
nvm install 16thennvm use 16check it usingnode -v, make sure it is node version 16]. - Facing access denied issue from nvm then open the terminal as run by administrator then try running above commands.
You can start coding right away but in order for us to organize the build, please follow these steps
- Open an issue in our gitHub repo https://github.com/web3ui/web3uikit/issues
- Give the issue a title prefixed with feature, bugFix, docs or chore
- Describe what you will build, or fix as best you can so we know what to expect
- Add any examples like images, design ideas or CodePen mockups
- Be open to refinement of your idea
- Stay in communication, once we accept the proposal we want that component. If you disappear we might finish it for you or pass it to another dev
- To complete your task and be merged, you should read about Pull Requests below
- In need of inspiration? Keep an eye on the issue board as our team will open issues for you and even add new designs for components we need, hot from our Moralis design UX team.
Just a friendly heads up incase you missed that above...
We have made a component called NewComp you can copy and paste this component to get started but don't change it or we will reject your pull request, sorry. Suggestions are welcome but we are pretty happy with it.
This component has an example of just about everything with a friendly non programmer comment to help you learn, how we do things, why we do them and what we expect when it comes to a pull request.
Lets take a tour and look at some of our standards
Simple stuff here, you can basically copy and paste. Its just an index file to give the end user an entry point to call in your awesome component.
This is where the storybook magic happens. Storybook allows you to build fast and test out state and prop changes in your component easily. You should checkout their docs here, https://storybook.js.org/docs/react/writing-docs/docs-page but its mainly boilerplate copy and paste in NewComp The important thing to remember is if your component has different states, for example an optional title. We want to see a story for with title and a story for without title. The next dev should be able to scroll your stories and see all versions / states / combinations of the component. Finally its cool to know that to save time we import our stories to be tested, this saves us coding the same thing twice and makes testing easy. Please follow the comments in the file and this should all be very simple.
Remember when CSS was the easy part? Global CSS is old school and would for sure either involve us using a crazy naming convention or causing CSS bugs in our users dApps, to resolve this problem we use Styled Components. You can find out more about Styled Components here: https://styled-components.com/docs You will see lots of comments in here to help you understand our structure, but here is some main take aways
Naming a styled element:
export const DivStyled = styled.divexport const SectionStyled = styled.sectionexport const H1Styled = styled.h1
See the pattern?
native element name=> so next dev can understand the markupStyled=> so next dev can see its a Styled Component
Do not forget these two sweet tips to make debugging easier!
DivStyled.displayName = 'MyNewComponent'
Adding this in the styles after the DivStyled is declared makes bugging with React dev tools easier
<DivStyled className="MyNewComponent">
Adding this in the markup will make it easy to debug any CSS issues you might face
Q: But what if there is two <div> tags in my component?
A: You can add an optional 3rd identifier of your choosing that helps make sense to the next dev
export const DivStyledWrap = styled.divorexport const DivStyledContent = styled.divorexport const DivStyledFlex = styled.div
BAD EXAMPLES:
export const Wrapper = styled.divexport const Title = styled.h2
Q: Why is that bad?
A: Because the next dev looks at <Wrapper /> tag and has no idea of its semantic meaning and sees nothing in the DOM that matches the word wrapper so they have to solve your puzzle, its not a hard puzzle sure but if the dev does not need to use brain power, its better DX
You will see a clear example of CSS sorting in action in the styles.tsx
- Imported styles (font, colors, etc)
- Normal styles (margin, padding, etc)
- Child elements (span, svg, etc)
- Pseudo elements (before & after)
- Modifier styles (hover, active etc)
- State changed styles
${(p) => (p.prop ? green : red)};
Note: each should be sorted alphabetically as best as possible. We use a VSCode plugin called SortLines by Daniel Imms
Q: Why such strict ordering?
A: Well it looks cleaner, its easy to review for us and it makes sense programmatically as base rules are then over written by interactions or state changes.
Q: Why sort alphabetically?
A: Because if the next dev wants to fix z-index they know to look at the bottom of the CSS properties, top DX. Also you'd be surprised how many elements out there have padding twice, alphabetical sorting makes this very obvious
Q: Can we add mad colors and fonts and such?
A: Nope, sorry. An entire team of skilled designers have made these calls for us, lets have faith in them
The first rule of web3uiKit club, no merge without all stories tested fully. You will see lots of simple testing examples for elements, text, styles, attributes all the things you would expect from normal React unit tests. A cool thing to note is we import all the stories and test them, this saves lots of time. Please try to keep to the boilerplate example we have provided and we have added lots of comments to help you get started with testing. Rule of thumb, if there is a prop or state change there should be a story, if there is a story, test it.
You will see lots of comments in here because we want to try and keep to the same layout to keep things easy for the next dev and for our pull request process.
- We import our Styled Component tags from the styles file, that is why naming the markup well is very important.
- We never recreate the wheel, in other words please use elements that we already have. We do not add new HTML for button and new SVG for icon, we already have those battle tested components. If a feature is lacking in
<Input />for example, open a pull request to ad the feature you need please. - Please follow the import order below
- Please follow this guide for the component internal structure below
- React, { React hooks }
- Other packages
- Internal components
- Props from .types interface
- Styles
- Destructure all props
- Set
consts anduseStates needed - Set other hooks like
useEffect - Set any internal functions that are needed, like
toggleStateinNewComp - Set extra
rendermethods so not all markup and logic is in one render function if needed. This might be overkill for your component but you can see a good example of this in<Input />and<Form />where the render method would have been too crazy to look at as one. - Render method will return your markup, but if this is complex with lots of logic think about the step above.
- Export that bad boy!
export default NewComp;
If you are new to TypeScript, fear not! Most of the features we use in this kit are pretty simple to understand, also there is an intro video by myself you can checkout. Don't stress this is a good way to learn and we are here to help. But here are some standards to follow.
- Use optional properties, we don't want the next dev to need to add 15 props to render a button, that would not be top DX
- Good use of non optional props... "what is a notification component without text?" Please do use non optional props. It stops the next dev making mistakes by missing props they will need.
- Passing render options rather than passing CSS, we want to take away the stress of HTML and CSS (more below in questions)
- Look at
<Input />its cool because it exports its validation interface to<Form />to make sure its strictly typed when called in. Could you make use of this principle in your component?
Q: Why not pass CSS
A: The next dev will add crazy properties and wonder why our kit is broken, lets reduce the questions and take care of the HTML and CSS for them.
Q: But things like background: string is cool, right?
A: Honestly we would rather not, we much prefer to use a theme or options like redColor or darkTheme or errorState to return one of the colors that our skilled and experienced team of designers picked. Also a silly dev could set it to 'foo-bar', that is a valid string after all but wont be a nice background color.
For your pull request please follow this guide
pull request type + component name + task
- so if i add a new
<KungFooBar />component my branch isfeat-kungfoobar-addedComp - or if i added validation to the
<Form />my branch isfeat-form-validation
Pull request types:
- feat = new feature
- fix = bug fix
- docs = added or changed documentation
- chore = some mindless work, like reformatting
So if i fix the validation to the <Form /> my branch is fix-form-validation... you get it, right? 😅
We follow a strict convectional commits pattern, and please if you change more than one component, then have 1 commit per components. No monster PRs please, its hard to review them if you change 500 files in one go, lol https://www.conventionalcommits.org/en/v1.0.0/
We are all students in this journey of life, so please accept any critique given. We are just trying to help you out or align your code with our base perhaps. This is a difficult but important part of collaboration and team work. We say this in the video but please, lets review each others code and PRs
Q: Why peer review?
A: So we can all learn from each other, the rising tide brings up all ships.
Don't forget we can approve and merge your code but you need to add your component to the projects base index.ts so the next dev can use it.
You will need
- vscode-styled-components by Julien Poissonnier
- Prettier by Haixin Chen
- Sort Lines by Daniel Imms
- Code Spell Checker by Street Side Software
If you really hate CSS thats ok, we can help you out. Hit me (billgil) up on Discord if you want help.
Jump over to the Moralis Discord and checkout the new channel web3uiKit feel free to ping @billgil, thats me and i'd love to help you out. Also your questions will help me to improve this doc.
All aboard! We didn't want to leave anyone behind so we made a video presentation. There is a ton of tips and help to get going in this video.
https://www.youtube.com/watch?v=bhOf56omPmA
Timestamps:
- 0:00 Intro
- 2:35 The repo
- 6:55 Setup
- 17:11 Storybook JS
- 27:58 React Typescript
- 42:04 Styled Components
- 55:38 Testing
- 72:07 Pull Request