Skip to content
This repository has been archived by the owner on May 28, 2019. It is now read-only.

[WIP] React-CDK v.3 #33

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion .eslintignore

This file was deleted.

6 changes: 0 additions & 6 deletions .eslintrc

This file was deleted.

24 changes: 23 additions & 1 deletion .gitignore
Original file line number Diff line number Diff line change
@@ -1,2 +1,24 @@
# See https://help.github.com/ignore-files/ for more about ignoring files.

# dependencies
node_modules
*.log

# testing
coverage

# publishing
dist

# development
test-cdk-scripts

# misc
.DS_Store
.env.local
.env.development.local
.env.test.local
.env.production.local

npm-debug.log*
yarn-debug.log*
yarn-error.log*
8 changes: 8 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,13 @@
## Changelog

### v3.0.0-alpha.0
24-September-2017

Work for updating to version 3 is started

* Add roadmap.md
* Init monorepo

### v2.0.2
26-August-2016

Expand Down
16 changes: 2 additions & 14 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ We welcome you help to make React CDK better. This document will help to streaml

No software is bug free. So, if you got an issue, follow these steps:

* Search the [issue list](https://github.com/kadirahq/react-storybook/issues?utf8=%E2%9C%93&q=) for current and old issues.
* Search the [issue list](https://github.com/storybooks/react-cdk/issues?utf8=%E2%9C%93&q=) for current and old issues.
* If non of that is helping, create an issue with with following information:
* Clear title (make is shorter if possible).
* Describe the issue in clear language.
Expand All @@ -18,21 +18,9 @@ No software is bug free. So, if you got an issue, follow these steps:
We welcome your contributions. There are many ways you can help us. This is few of those ways:

* Fix typos and add more documentation.
* Try to fix some [bugs](https://github.com/kadirahq/react-cdk/labels/bug).
* Try to fix some [bugs](https://github.com/storybooks/react-cdk/labels/bug).
* Add new features (try to discuss with what are building by creating an issue).

Before you submit a new PR, make you to run `npm test`. Do not submit a PR if tests are failing. If you need any help, create an issue and ask.

## Development Guide

This is Yeoman generator. There are two generators, which are:

* app - main generator creates the project
* update - which update an existing project

Before you start developing, you need to get familiar with yeoman first. Refer following links:

* [Yeoman getting started guide](http://yeoman.io/learning/)
* [Creating a yeoman generator](http://yeoman.io/authoring/)

Then link this project with `npm link`. Then you can try `yo react-cdk` and it'll use your development repo.
227 changes: 3 additions & 224 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,226 +1,5 @@
# React CDK
# React-CDK v.3

[![Storybook Slack](https://now-examples-slackin-nqnzoygycp.now.sh/badge.svg)](https://now-examples-slackin-nqnzoygycp.now.sh/)
This branch is under development. Any help with code review, bug reporting/fixes, ideas, wishes, objections, PR creation, docs writing is very appreciated! If you are interested, please contact us in the [Storybook Slack](https://now-examples-slackin-nqnzoygycp.now.sh/).

### Component Development Kit for React

##### We are looking for an active maintainer for this repository. React CDK has been put on hold and may become deprecated in the future so our core team can focus on Storybook. If you are interested, please contact us in the [Storybook Slack](https://now-examples-slackin-nqnzoygycp.now.sh/).

React CDK is not just another React boilerplate. With React CDK, you can focus on developing your React component or utility while React CDK takes care of all the other stuff.

> Read why [Kadira created React CDK](https://voice.kadira.io/say-hello-to-react-cdk-97cff692e798#.2aaodkb6c).

React CDK comes with following features:

* Create a project with a single command.
* Write your component in [ES2016+ syntax](https://www.npmjs.com/package/babel-preset-react-app).
* Develop in a live environment with [React Storybook](https://github.com/kadirahq/react-storybook/).
* Write tests with Mocha and [Enzyme](https://github.com/airbnb/enzyme).
* Use ESLint with the [Airbnb style guide](https://github.com/airbnb/javascript).
* Publish correctly transpiled code into NPM.
* Deploy your storybook to GitHub Pages.
* Get **updates** to core building tools.

## TOC

* [Getting Started](#getting-started)
* [Developing Your Component](#developing-your-component)
* [Testing](#testing)
* [Lint Rules](#lint-rules)
* [Publishing](#publishing)
* [Deploying Storybook](#deploying-storybook)
* [CSS and Styles](#css-and-styles)
* [Updating Your Component with React CDK](#updating-your-component-with-react-cdk)
* [Customizing the Component](#customizing-the-component)

## Getting Started

Install React CDK with the following command:

```
npm install -g yo generator-react-cdk
```

> React CDK comes as a [yeoman](http://yeoman.io/) generator, which allows you to scaffold your component quickly.


Then, create your first component library with the following command:

```
yo react-cdk react-wizard
```

![Creating a project with React CDK](docs/create-project-with-react-cdk.png)

> React CDK will create a directory called react-wizard with all the files you need to get started.


Visit that directory and install the NPM dependencies:

```
cd react-wizard
npm install
```

By default, this project contains a simple button created with React. It also includes tests and [React Storybook](https://github.com/kadirahq/react-storybook/) stories so you can get ideas for writing your own stories.

## Developing Your Component

Now we need to work with the component. Your component lives under the src directory. Open `src/index.js` in your favorite editor and start developing.

Now, it’s time to start the Storybook so we can see what we are building:

```
npm run storybook
```

The above command starts the Storybook console on [http://localhost:9010](http://localhost:9010/).

![React Storybook](docs/storybook.png)

> You can see changes you make while you are editing your component. Visit [React Storybook](https://github.com/kadirahq/react-storybook/) repo to learn more.


You can write your component in ES2015+ syntax. It supports `react` and `babel-stage2` presets.

## Testing

You can write your tests inside the `src/tests` directory. By default, the project comes with two test cases demonstrating how to write tests. React CDK configures your component with Mocha, [Enzyme](https://github.com/airbnb/enzyme), jsdom, and other essential JS testing tools.

This is the ideal way to write React tests.

You can run tests with the following commands:

* `npm run testonly` (run tests once)
* `npm run test-watch` (run tests and watch for changes)
* `npm test` (run tests and apply lint rules)

## Lint Rules

Your project is configured with ESLint based on the [Airbnb JavaScript style guide](https://github.com/airbnb/javascript) with some minor changes.

You can apply lint rules with the following commands:

* `npm run lint` (apply lint rules)
* `npm run lintfix` (apply lint rules and fix some common issues)

## Publishing

Now it’s time to publish your component to NPM. Before you publish, make sure you’ve customized the following files as necessary:

* package.json
* README.md
* CONTRIBUTE.md
* LICENSE

If everything is okay, simply publish your component to NPM with the following command:

```
npm publish
```

This command will transpile your component for ES5 before publishing it to NPM. Your component will work on any JavaScript environment.

## Deploying Storybook

You will usually write your stories while you are developing your component. That allows you to use your storybook as a living document. You could show what your component looks like and different ways to use it.

Then you can simply deploy it to GitHub Pages with the following command:

```
npm run publish-storybook
```

You can link your Storybook URL inside the README file.

Here’s a [sample component](https://github.com/kadira-samples/react-button) listing a Storybook URL.


> You can also publish your storybook automatically when you publish your component to NPM. To do that, simply add the following NPM script to your package.json file:

```js
{
"scripts": {
...
"postpublish": "npm run publish-storybook"
...
}
}
```

## CSS and Styles

It’s common to include CSS and Styles with your component. There are many ways to do this. Some prefer to write CSS in JS, while some provide a CSS file that lives inside the repo.

### CSS in JS

With this approach, you don’t need to configure anything. You can just use it. However, you should make sure you accept some external styles, which allows the end user to change the look and feel of your component as needed.

### Plain old CSS files

If you are following this approach, make sure to place your CSS files inside the root of your component and not inside the src directory. Then, your end users can import it like this:

```js
import 'my-comp/style.css'
```

You may also need to load this style sheet inside your stories. Simply import the above style sheet into src/stories/index.js with the following command:

```
import '../../style.css'
```

## Updating Your Component with React CDK

This is a plain NPM module without any magic. However, it’s written in a way that allows us to push updates to your repo.

You never need to worry about updating dependencies and build tools. React CDK will take care of that.

First, update React CDK with the following command:

```
npm install -g generator-react-cdk
```

Then, visit your project and apply the following command:

```
yo react-cdk:update
```

This will update the core build tools and the package.json file for dependencies.


> It won’t update dependencies you’ve added; it will only update the dependencies and NPM script React CDK has added.

## Customizing the Component

Since your component is a plain NPM module, you can customize it any way you want. Here are some ways to do so:

### Add dependencies

You can add dependencies to the `package.json` file as needed.

### Change the JavaScript environment

Sometimes you may want to use cutting-edge JavaScript features. You can simply add the necessary Babel preset and change the `.babelrc` file.

### Change other dotfiles

You can change any of the dotfiles, including `.gitignore` and `.npmignore`.

### Customize Storybook

Sometimes you may need to customize your React Storybook. If you do, you’ll usually customize the `.storybook/webpack.config.js` file. Go ahead and do it.

### Add some pre-publish code

React CDK already uses the NPM `pre-publish` hook, so you won’t be able to use it directly. Instead, you can use `.scripts/user/prepublish.sh` to add your own code.

### Configure test utilities

We have included JSDOM(to support enzyme's [full DOM rendering](https://github.com/airbnb/enzyme/blob/master/docs/api/mount.md)) and Babel configurations before running Mocha tests. If you want to add more stuff, simply use the `.scripts/user/pretest.js` file.

### Configure something else

You can configure this project in many ways. Give it a try, and I bet you can do it without our help. If you need help from the core React CDK tools, just create [an issue](https://github.com/kadirahq/react-cdk/issues).
See [Roadmap](ROADMAP.md)
51 changes: 51 additions & 0 deletions ROADMAP.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
# Roadmap

This project is going to be a CRA and @Storybook/CLI based minimalistic boilerplate focused on the components development. General settings will be left to the CRA which is used as a dependency, while React-CDK provides only special scripts and project templates.


## Project development

- create `cdk-scripts` package to wrap `react-scripts`
- use `cdk-scripts` as a custom scripts with CRA
- launch `getstorybook` from `cdk-scripts`
- create `create-react-cdk` package as a CLI for creating projects
- use `create-react-cdk` to launch `create-react-app` internally
- add `publish` script to `cdk-scripts`
- add `pack` script to `cdk-scripts` (publish:local)
- add `deploy` script to `cdk-scripts`
- add user templates support
- add default React-CDK template
- `create-react-cdk` should always use the latest version of `cdk-scripts`
- setup yarn workspace
- add docs & tests
- update CONTRIBUTING guide


## Features

- setup [Displaying Lint Output in the Editor](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#displaying-lint-output-in-the-editor)

- add prettier support

- setup [Debugging in the Editor](https://github.com/facebookincubator/create-react-app/blob/master/packages/react-scripts/template/README.md#debugging-in-the-editor) (for VSCode)

- bundle libraries with webpack


## Templates

- default template

*Provides minimum required settings*

- storybook-kitchen-sink

*Goes with full @storybook/cra-kitchen-sink addons equipment*

- storybook boilerplate

*Creates the well-balanced development environment with most useful addons set from Storybook Addons Gallery*

- addon development

*Special template ready for the new Storybook addon creation/development*
Binary file removed docs/create-project-with-react-cdk.png
Binary file not shown.
1 change: 1 addition & 0 deletions docs/readme.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
# Docs folder
Binary file removed docs/storybook.png
Binary file not shown.
Loading