Skip to content

Commit

Permalink
[patch][chore] Update Readme component archetype (#528)
Browse files Browse the repository at this point in the history 
* # This is a combination of 2 commits.
# This is the 1st commit message:

Update component archetype readme

# The commit message #2 will be skipped:

#	# This is a combination of 2 commits.
#	# This is the 1st commit message:
#
#	Update component archetype readme
#
#	# The commit message #2 will be skipped:
#
#	#	update electrode component readme

* code review

* code review readme
  • Loading branch information
@didi0613 @jchip
didi0613 authored and jchip committed Aug 14, 2017
1 parent bb2af69 commit f81feec
Show file tree
Hide file tree
Showing 3 changed files with 72 additions and 141 deletions.
2 changes: 1 addition & 1 deletion packages/electrode-archetype-react-app/FAQ.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -121,5 +121,5 @@ Using `AboveTheFoldOnlyServerRender` you can avoid caching of certain components
```

AboveTheFoldOnlyServerRender [example](https://github.com/docs-code-examples-electrode-io/electrode-progressive-beer/blob/master/client/components/home.jsx#L69-L83)
Sample [config.js](https://github.com/electrode-io/electrode-boilerplate-universal-react-node/blob/master/config/sw-config.js)
Sample [config.js](https://github.com/electrode-io/electrode/blob/master/samples/universal-react-node/config/sw-config.js)
More on [PWA](https://developers.google.com/web/progressive-web-apps/)
53 changes: 53 additions & 0 deletions packages/electrode-archetype-react-component/FAQ.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
#### What is this for?

This "component archetype" provides for common patterns across all component projects so that each component project can standardize on common development behavior and patterns. Its essentially pre-made patterns for build scripts.

#### How do I start with my own component?

You should start your component by using our Yeoman `generator-electrode`. Check our Electrode getting started guide [here](https://docs.electrode.io/chapter1/quick-start/start-with-component.html).

#### What's inside Electrode component?

The electrode component is applied by Lerna structure, which can help manage multiple repos within your `packages` directory.

`demo-app` directory is a full stack Electrode application, which used for developing and testing your components. You need to import your `packages/<componentName>` to demo-app, explore and personalize this web application there.

`packages` directory is where your packages located at. Inside, `demo` folder contains examples for how to demo your components, `src`|`test` folder contains your component `source|test` code, and `xclap.js` is the entry to Electrode archetype tasks.

#### How do I start developing in my component project after installing?

> NOTE: `demo-app` directory is used for developing and testing your components, to demo your packages, please make sure you are under `demo-app` folder.
```bash
# This runs both the node server and webpack (in hot mode)
$ clap hot

# Also try `dev` mode when running off battery power and you wish to maximize battery life.
$ clap dev
```

#### What is `hot mode`?

`Hot mode` enables Hot module reloading(HMR), it is where webpack transpiles your javascript and css code and continues to watch for any changes, and, builds and loads only the code that has changed on disk. It allows you to develop without re-loading your browser page as the changes will be automagically piped in.

#### How do I run my component tests?

```bash
# This will run test eslint and your spec tests
$ clap check
```

#### How do I run my component tests without going through eslint (i.e., while I'm developing)?

```bash
# This will run only your spec tests
$ clap test-dev
```

#### Where can I find the sample of Electrode component?

Please check out the Electrode component demo [here](https://github.com/electrode-io/electrode/tree/master/samples/demo-component).

#### Where can I find a detailed tutorial about Electrode component?

Please check out the Electrode component tutorial [here](https://docs.electrode.io/chapter1/quick-start/start-with-component.html).
158 changes: 18 additions & 140 deletions packages/electrode-archetype-react-component/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,169 +4,46 @@

Electrode flavored react component archetype.

## Creating A New Component
Have a question? Check the [FAQ](./FAQ.md)

First, install [yeoman](http://yeoman.io/) to help quickly create an empty component:
## Installation

```bash
$ npm install -g yo
```
You are suppose to start your Electrode component by using our Yeoman generator-electrode.

Now, `yo` can scaffold the project for you.
Electrode team offers a detailed getting started with Electrode Component tutorial.
If you want to check out more on our Electrode component, please use the instructions [here](https://docs.electrode.io/chapter1/quick-start/start-with-component.html) as a guide.

```bash
$ yo electrode-component
```
## Usage

You should see something similar to the below session:
The primary interface to the archetype is a list of tasks you can invoke with clap to do your bidding.
To see the tasks, simply run:

```bash
$ yo electrode-component

Welcome to the Electrode Component generator

Were going to set up a new Electrode Component, ready for development with
react, webpack, demo, electrode component archetype, live-reload

? What is your Package/GitHub project name? (e.g., 'wysiwyg-component') product-card
? What is the ClassName for your component? ProductCard
? What will be the npm package name? product-card
? What will be the GitHub organization username (e.g., 'walmartlabs')? electrodeio
? What is your name? (for copyright notice, etc.) arpan nanavati
? What is your GitHub Username? ananavati
? What is the name of the GitHub repo this will be published at? product-card
? Would you like to create a new directory for your project? Yes


create .babelrc
create .gitignore
create .npmignore
create .editorconfig
create xclap.js
create package.json
create README.md
create src/components/product-card.jsx
create src/styles/product-card.styl
create src/index.js
create test/client/.eslintrc
create test/client/components/product-card.spec.jsx

Your new Electrode Component is ready and your component is in '/src'.
$ clap
```

## Configuring an existing project / manual setup

If you prefer to create your component manually or if you have an existing component that you want to migrate to using this archetype, follow the instructions below:

###### run the following in your project
To demo your `packages/components`, for example, the dev task, go to your `demo-app` directory and run:

```bash
$ npm install --save-dev electrode-archetype-react-component electrode-archetype-react-component-dev
$ clap dev
```

###### Add a `.babelrc` to your project

The `.babelrc` needs to extend
[the archetype's babel configuration](config/babel/.babelrc) in order to apply the presents (ES2015, React) and the plugins like i18n. If your project needs additional Babel settings (like using stage 0 features) you can add them to this file. See the [Babel docs](https://babeljs.io/docs/usage/babelrc/) for more information.
To test your components, go to your root directory and run:

```json
{
"extends": "./node_modules/electrode-archetype-react-component/config/babel/.babelrc"
}
```bash
$ npm run test
```

###### Add a `xclap.js` to your project

The `xclap.js` needs to extend
[the archetype's clap tasks](/arhcetype-clap.js) in order to apply the shared tasks on your new/existing electrode component. Add this following lines of code to the newly created `xclap.js`

```js
"use strict";

const xclap = require("xclap");
To test a single component, go to your specific 'packages/component' directory and run:

const tasks = {
"prepublish": ["npm:prepublish"],
"preversion": ["check-cov"]
}
xclap.load("myprj", tasks);

require("electrode-archetype-react-component")(xclap);
```bash
$ clap check
```

## Managing Dependencies

The archetypes are split into two parts: `<archetype>` and `<archetype>-dev`. Both archetypes need to be in each component and should be included in the `package.json`'s `devDependencies`.

* * *

## Project Structure

This archetype assumes an architecture as follows:

```text
archetype
config.js
src
components/
*.jsx
styles/
*.css
index.js
test
client/
spec/
components/
*.jsx?
*.jsx?
main.js
test.html
.babelrc
package.json
```

## CSS Modules + CSS next

By default, this archetype assumes you are using CSS-Modules + CSS-Next, you need
to opt-in to stylus support by adding a `*.styl` to your _project's_ `demo/demo.styl` & `src/styles/*.styl`.
You can use stylus and CSS-Modules together by enabling setting the 'cssModuleStylusSupport' option in
`archetype/config.js` to `true`.

Import css files in your components and reference class names via the exported object `src/components/your-component.js`:

```javascript
import React from "react";

import styles from "../styles/your-component.css";

class YourComponent extends React.Component {
render() {
return (
<div className={styles.someStyle}>Hello Modules!</div>
);
}
}
```

Add following styling to `src/styles/your-component.css`

```css
:root {
--black: #000;
--white: #fff;
}

.baseStyle {
background-color: var(--black);
color: var(--white);
}

.someStyle {
composes: baseStyle;
font-size: 18px;
}
```

## Check the archetype configs:

If you are enhancing / refactoring this archetype and have locally checked it out,
Expand All @@ -178,6 +55,7 @@ The main check we provide for the archetype itself is:
$ clap archetype:check
```


Built with :heart: by [Team Electrode](https://github.com/orgs/electrode-io/people) @WalmartLabs.

[npm-image]: https://badge.fury.io/js/electrode-archetype-react-component.svg
Expand Down

0 comments on commit f81feec

Please sign in to comment.