diff --git a/packages/electrode-archetype-react-component/FAQ.md b/packages/electrode-archetype-react-component/FAQ.md new file mode 100644 index 0000000000..0e10bb8356 --- /dev/null +++ b/packages/electrode-archetype-react-component/FAQ.md @@ -0,0 +1,51 @@ +#### 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. + +#### What made this new component archetype different? + +The new electrode component is applied by Lerna structure, which can help manage multiple repos within your `packages` directory. + +`demo-app` folder is a full stack Electrode application, which used for developing and testing your components. You need to import your `packages/` to demo-app, explore and personalize this web application there. + +`packages` folder 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? + +Since `demo-app` is a full stack Electrode Application, which used for developing and testing your `packages/component`, to run|demo your packages, please make sure you are in `demo-app` folder. + +```bash +# This runs both the node server and webpack (in hot mode) +$ cd demo-app +$ clap hot + +# Also try `dev` mode when running off battery power and you wish to maximize battery life. +$ cd demo-app +$ 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 a sample of Electrode component? + +Please checkout 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 checkout the Electrode component tutorial [here](https://docs.electrode.io/chapter1/quick-start/start-with-component.html). diff --git a/packages/electrode-archetype-react-component/README.md b/packages/electrode-archetype-react-component/README.md index 46a328d8e2..413b4cce63 100644 --- a/packages/electrode-archetype-react-component/README.md +++ b/packages/electrode-archetype-react-component/README.md @@ -4,75 +4,19 @@ 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 -``` - -Now, `yo` can scaffold the project for you. - -```bash -$ yo electrode-component -``` - -You should see something similar to the below session: - -```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'. -``` - -## Configuring an existing project / manual setup +> NOTE: Generally you don't need to install these modules directly. You should start your component by using our Yeoman generator-electrode or check our Electrode [Get Started With Electrode Component](https://docs.electrode.io/chapter1/quick-start/start-with-component.html) guide. -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: +However, if you are manually creating your component: -###### run the following in your project +###### Install the two complementary modules -```bash -$ npm install --save-dev electrode-archetype-react-component electrode-archetype-react-component-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. - -```json -{ - "extends": "./node_modules/electrode-archetype-react-component/config/babel/.babelrc" -} +$ npm install --save electrode-archetype-react-component +$ npm install --save-dev electrode-archetype-react-component-dev ``` ###### Add a `xclap.js` to your project @@ -94,77 +38,62 @@ xclap.load("myprj", tasks); require("electrode-archetype-react-component")(xclap); ``` -## Managing Dependencies +## Usage -The archetypes are split into two parts: `` and `-dev`. Both archetypes need to be in each component and should be included in the `package.json`'s `devDependencies`. +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 +$ clap +``` -## Project Structure +To invoke a task, for example, the dev task, run: -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 +```bash +$ clap dev ``` -## 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`. +## Managing Dependencies -Import css files in your components and reference class names via the exported object `src/components/your-component.js`: +The archetypes are split into two parts: `` and `-dev`. Both archetypes need to be in each component and should be included in the `package.json`'s `devDependencies`. -```javascript -import React from "react"; -import styles from "../styles/your-component.css"; +## Project Structure -class YourComponent extends React.Component { - render() { - return ( -
Hello Modules!
- ); - } -} +``` +electrode-component + ├── demo-app + │ ├── LICENSE + │ ├── README.md + │ ├── config + │ ├── xclap.js + │ ├── src + │ │ ├── client + │ │ └── server + │ └── test + │ ├── client + │ └── server + └── packages + └── + ├── README.md + ├── xclap.js + ├── package.json + ├── demo + ├── src + │ ├── components + │ ├── index.js + │ ├── lang + │ └── styles + └── test + └── client ``` -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; -} +``` +demo-app - This directory is a full stack Electrode Application, which used for developing and testing your packages/. You need to import your packages/ to demo-app, explore and personalize this web application there. +packages//xclap.js - Entry to Electrode archetype tasks +packages//demo - Contains examples for how to demo your component +packages//src - Contains your component source code +packages//test - Contains unit tests for your component ``` ## Check the archetype configs: