- Before contributing
- New Feature Checklist
- Framework Structure
- Demo Application
- Documentation
- Development
- Release
- Don’t overcomplicate
- Don’t make things too abstract
- Use tslint, to check the code style
- Never forget document your changes add create some examples
- Write tests
- Create showcase components per each new component/feature
- Lint checks are passing
- Tests are added or updated and passing
- Showcase components in Kitten Tricks application added or updated
- Showcase components in documentation application added or updated
- Readable documentation added or updated
- Commit message is properly formatted
- Looks great on all default themes
- Requires approval from several core team contributors
- docs - Documentation and framework website built on top on the framework
- src
- components -
@ui-kitten/componentspackage. UI components itself. - eva-icons -
@ui-kitten/eva-iconspackage. Eva Icons for React Native - date-fns -
@ui-kitten/momentpackage. Services that allows UI Kitten components to work with date-fns. - moment -
@ui-kitten/momentpackage. Services that allows UI Kitten components to work with moment.js. - template-js -
@ui-kitten/template-jspackage. Template app for creating UI Kitten project with React Native CLI. - template-ts -
@ui-kitten/template-tspackage. Template app for creating TypeScript UI Kitten project with React Native CLI. - Demo Application - independent application with runnable examples for each feature
- components -
Located in ./src/components. Divided into two dirs:
- theme - Contains styling services and supporting components used to provide styles to basic components.
- ui - Contains basic UI components.
Located in ./src/components/theme
- theme - ThemeProvider component. Used to provide one of Eva themes used to style basic components.
- mapping - MappingProvider component. Used to provide one of Eva mappings to style basic components.
- style - StyleProvider components. This mixes both Theme- and Mapping- providers to provide usable basic component style object.
- application - Global ApplicationProvider component. This mixes StyleProvider implementation with Eva processing engine.
Located in ./src/components/ui
Each component implementation can be found in a directory with the corresponding name.
*.component.tsx- component implementation itself.*.spec.tsx- component tests.*.spec.tsx.snap- component test snapshots. This is a generated file. Could be presented or not depending on tests.
Some of the components can have a more complex implementation. In this case, the final component implementation could be divided into sub-components, but tests should be written in a single *.spec file. The good example is TabView.
Kitten Tricks is an example app built on top of the Expo containing reusable screens and runnable component examples. This application is used as a framework demo.
Before running, please make sure to clone UI Kitten, Eva Design System and Kitten Tricks:
-
Clone UI Kitten
git clone https://github.com/akveo/react-native-ui-kitten -
Clone Eva Design System
git clone https://github.com/eva-design/eva -
Clone Kitten Tricks
git clone https://github.com/akveo/kittenTricks -
IMPORTANT Ensure you have the following structure of repos:
- /
- eva
- kittenTricks
- react-native-ui-kitten
- Run
yarnfrom react-native-ui-kitten directory to install dependencies
yarn demo env devto switch to development environmentyarn demo expo startto start as Expo project oryarn demo startto start as Bare React Native project.
yarn demo env prodto switch to production environmentyarn demo expo startto start as Expo project oryarn demo startto start as Bare React Native project.
Documentation is a separate Angular application located right in this project in docs folder.
The pages structure is taken from structure.ts file.
The components documentation is taken from the component comment sections.
Documentation is generated by the custom generator built on top of UI Kit. You have to use typedoc everywhere for the documentation purpose.
Docs application split into the sections which you can find in the app's sidebar.
Each section contains some pages.
If you wanna add new page in the documentation, please, open structure.ts
file in the root of docs application and add a new page in the required section:
{
type: 'page',
name: 'Awesom page',
children: [
... blocks
],
},
If it's a completely new feature, maybe it would be better to create a new section:
{
type: 'section',
name: 'New super section',
children: [
... pages
],
},
Page can contain multiple blocks of the following types:
Renders plain markdown file from the articles dir.
For example, if you wanna add getting started article you have to do the following:
- put
getting-started.mdfile in thearticlesfolder. - add markdown block to the page children:
{
type: 'block',
block: 'markdown',
source: 'getting-started.md',
},
If you have to render all the information about component parsed with typedoc you have to use component blocks:
{
type: 'block',
block: 'component',
source: 'MyNewComponentName',
},
Tabbed component block will render component description splitted on the following tabs:
- Overview - This is typedoc comment above component
- Theme - Theme variables listed in the typedoc comment above component with
@stylestag, for example:
/**
* ...
*
* @styles
*
* var1
* var2
*
* ...
*/
- API - parsing result of the typedoc above public methods and props
- Examples - live examples listed in the typedoc comment above component
If you wan't to describe a small thing in two lines of code you can just add something similar in your typedoc comment:
```jsx
const AwesomeComponentShowcase = () => (
<AwesomeComponent/>
);
```
And don't forget to specify the language above your example.
- create directory in
./src/components/ui/awesomeComponentwith following files:
- awesomeComponent.component.tsx (component file)
- awesomeComponent.spec.tsx (component tests)
- create directory in Kitten Tricks
./src/scenes/components/awesomeComponentwith following files:
- awesome-component.component.tsx (component showcase container)
- awesome-component-showcase.component.tsx (basic component showcase)
- type.tsx (component configuration file)
Look through already existing showcases and use similar implementation (e.g Button Showcase)
- register your showcase in a Demo Application:
Open Components Navigator and expand navigation with your component container:
import { AwesomeComponentScreen } from '../scenes/components/awesome-component.component';
...
<Stack.Screen name='AwesomeComponent' component={AwesomeComponentScreen} />
Open Components Screen and expand it with route to new component:
{
title: 'AwesomeComponent',
route: 'AwesomeComponent',
...
}
- For major version, search for
@breaking-changeto make sure all breaking changes are covered.
To start a new release (publish the framework packages on NPM) you need:
- Setup node 14 environment (the latest is v14.21.3 with npm 6.14.18). Consider using a node manager, e.g. n.
- Create a new release branch with template
release/vX.X.X - MANUALLY update a version in main ./package.json to a new one
- Check eva dependencies (if the release requires its changes)
- Run tests:
yarn lint && yarn test - Run build:
yarn build - Generate changelog:
yarn bump-version - Fix/expand changelog manually
- Update documentation (e.g DEV_DOCS.md) files if needed
- Push the branch, create PR, approve - merge
- Pull the upstream (master or another version branch (e.g. 4.0.1, next))
- Verify that React Native CLI works properly with local JS template
npx react-native init MyApp --template file:///path-to/react-native-ui-kitten/src/template-js). See CLI docs. - Verify that React Native CLI works properly with local TS template
npx react-native init MyApp --template file:///path-to/react-native-ui-kitten/src/template-ts). See CLI docs - Publish documentation:
yarn publish-docs - Publish framework packages:
yarn publish-packages(make sure that you are logged into ui-kitten npm account before) - Create and push git tag
git tag vX.X.X && git push origin vX.X.X - Create release on GitHub for the tag