Skip to content

Commit 087bce5

Browse files
EByrdSEByrdS
authored
Merge pull request #9 from EByrdS/update-readme
Explains gulpfile and processes
2 parents a758a11 + 12b9b92 commit 087bce5

File tree

1 file changed

+171
-40
lines changed

1 file changed

+171
-40
lines changed

‎README.md

+171-40
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ historical foreign exchange (forex) rates published by the European
77
Central Bank.The API updates rates daily around 4PM CET every working day.
88
Historical rates go back to 1st January, 1999.
99

10-
### Disclaimer
10+
## Disclaimer
1111
This app was created as an individual proyect to understand the groundings
1212
of SPAs, React, SASS, gulp and other dependencies. Due to the large
1313
ammount of information, the tools used may not be fully exploited or may contain
@@ -17,45 +17,46 @@ much welcomed.
1717
This application comes with **no warranty** of any kind. Its data is obtained
1818
through [fixer.io](fixer.io) which in turn comes with **no warranty** as well.
1919

20-
### Creation
21-
This application was created with the following commands, in a C9 environment
22-
1. npm init
23-
2. npm install --save react react-dom
24-
3. npm install --save-dev babel-cli babel-preset-env babel-preset-react
25-
4. sudo npm install gulp -g
26-
5. npm install --save-dev pump
27-
6. npm install --save-dev gulp
28-
7. npm install --save-dev gulp-sass
29-
8. npm install --save-dev browser-sync
30-
9. npm install --save-dev gulp-sourcemaps
31-
10. npm install --save-dev gulp-uglify
32-
11. npm install --save-dev gulp-clean-css
33-
12. npm install --save-dev gulp-html-replace
34-
13. npm install --save-dev gulp-connect
35-
14. npm install --save-dev vinyl-source-stream
36-
15. npm install --save-dev browserify
37-
16. npm install --save-dev watchify
38-
17. npm install --save-dev gulp-streamify
39-
18. npm install --save-dev babelify
40-
19. npm install --save-dev gulp-concat
41-
20. npm install -g jest
42-
21. npm install --save-dev babel-jest
43-
22. npm install --save-dev jest
44-
23. npm install --save-dev jest-cli
45-
24. npm install --save-dev enzyme
46-
25. npm install --save-dev enzyme-adapter-react-16
20+
## Using the app
21+
Once you have access to the code, and have installed `npm` (C9 have it installed
22+
by default), you need only to execute the following commands.
23+
24+
First install `gulp` and `jest`, as they are needed in the process.
25+
```shell
26+
npm install -g gulp
27+
npm install -g jest
28+
```
29+
> NOTE: You may need to prefix `sudo` for this commands to work:
30+
`sudo npm install -g gulp`.
31+
32+
Download the corresponding `npm` packages. These packages are specified in the
33+
`package.json` file. The command will create a `node_modules` directory.
34+
```shell
35+
npm install
36+
```
37+
38+
Create the `dev` folder and open a listening port.
39+
```shell
40+
npm start
41+
```
42+
43+
Or create the production's `dist` folder and open a listening port.
44+
```shell
45+
gulp production
46+
```
4747

48-
### Testing
49-
Watch files and run their respective test with Jest:
50-
```bash
48+
### Begin the Test Driven Development (TDD) cycle.
49+
```shell
5150
npm test
5251
```
53-
> NOTE: This command will execute `jest --watch`. It will run in the terminal
54-
the tests corresponding to changed files.
52+
> NOTE: This npm command is defined in the `package.json`, it will run
53+
`jest --watch`. Changes to `.js` and `.test.js` files will trigger the execution
54+
of their individual tests. Run all test with `jest` or pressing `a` while its
55+
interface is open.
5556

5657
### Development
5758
Build *dev* directory and listen with browserSync:
58-
```bash
59+
```shell
5960
npm start
6061
```
6162
This will transform all JSX into JS, and SASS into CSS.
@@ -65,10 +66,13 @@ The corresponding changes to the `index.html` tags are made automatically.
6566
> NOTE: `npm start` will execute the `gulp` script, which in turn
6667
executes gulp's `'default'` task. You can see this task in the `gulpfile.js`
6768
file. This command behaves exactly as `gulp` or `gulp default`.
69+
A port to listen and display this directory is created
70+
through `browsersync`. The `gulpfile.js` is instructed to refresh all browsers
71+
when there is a change in the `app` directory, getting live feedback o changes.
6872

6973
### Production
7074
Build *dist* directory and listen with browserSync:
71-
```bash
75+
```shell
7276
gulp production
7377
```
7478
This will transform all JSX into JS, and SASS into CSS. It will
@@ -78,8 +82,135 @@ from `.scss` files) into a single `styles.min.css` file. The corresponding
7882
changes to the `index.html` file, regarding `<script>` and `<link>` tags are
7983
automatically made to match the created compact version.
8084

81-
### References: Getting started
82-
* [React](https://reactjs.org/docs/add-react-to-an-existing-app.html#installing-react)
83-
* [Babel](https://babeljs.io/docs/setup/#installation)
84-
* [Gulp](https://css-tricks.com/gulp-for-beginners/)
85-
* [Building React applications with Gulp and Browserify](https://tylermcginnis.com/react-js-tutorial-pt-2-building-react-applications-with-gulp-and-browserify/)
85+
## Gulpfile explained
86+
The process of code transformation is carried out with `gulp`, the instructions
87+
are found in the `gulpfile.js` file. The tool
88+
[pump](https://www.npmjs.com/package/pump) is used for easier
89+
debugging of the `gulpfile.js`.
90+
91+
### 'default'
92+
This is the process executed with the shell command `gulp`, in this proyect
93+
it is executed also with `npm start`.
94+
95+
The tasks executed are:
96+
1. `'sass'`
97+
2. `'transform'`
98+
3. `'replaceHTML-dev`
99+
4. `'copy-public-dev'`
100+
5. `'serve'`
101+
102+
### 'sass'
103+
Take all the files in the `app/css` directory with a `.scss` file extension.
104+
105+
The files will be compacted and minified, a sourcemap is needed to debug this
106+
file, otherwise errors will be shown as relative to the minified `.css` file
107+
which are useless for development intentions. This is done with
108+
`sourcemaps.init()` and `sourcemaps.write()`.
109+
110+
Take all `.scss` files and transform them into readable CSS code.
111+
112+
`gulp-clean-css` is used to eliminate unnecesary code in the resulting `.css`
113+
file, making it lighter and thus faster to load for the browser.
114+
115+
Concatenate all the code into a single file called `styles.min.css`. Finally
116+
place this file in the `dev` folder and reload all browsers with `browsersync`
117+
to see their effect.
118+
119+
### 'transform'
120+
A `'watcher'` is created with `watchify` and `browserify`. This watcher needs
121+
only to receive the first `.js` file and will find all the other ones through
122+
the `import` instructions.
123+
124+
All the JSX code is transformed into readable JS with `babelify`. Babelify in
125+
turn uses the presets `react` and `env` (in `package.json`) to know how to
126+
behave.
127+
128+
Debug is set to `true` and the options `cache`, `packageCache` and `fullPaths`
129+
are needed for watchify to properly work.
130+
131+
When there is an `'update'`, the `bundle` function will be executed. This
132+
function contains the same code as the `'transform'` gulp task.
133+
134+
The `'transform'` task creates a "bundle" of these JS files and writes the
135+
output inside the `dev` directory, with the filename `build.js`.
136+
137+
### 'replaceHTML-dev'
138+
As JS and CSS files are concatenated into new compact versions, the `index.html`
139+
file needs to know where they are located and how they are named.
140+
141+
The `index.html` file is taken, and the code inside the `<!-- build:js -->`
142+
and `<!-- build:css -->` tags is changed to point to the correct created files.
143+
144+
### 'copy-public-dev'
145+
This process takes all files inside the `public` directory and copies them
146+
exactly into the `dev` folder.
147+
148+
### 'serve'
149+
A server is connected with `gulp-connect`. `browser-sync` is initialized.
150+
151+
Gulp will watch changes with the `gulp.watch` commands. Changes to SCSS files
152+
will trigger the transformation of SCSS into the single CSS file and reload
153+
browserSync. Changes to JS files trigger only the browserSync to reload, as its
154+
transformation process is handled with the `watcher.on('change', bundle)`
155+
instruction.
156+
Changes to the `index.html` file trigger its copy and tag replacement, followed
157+
by the reload of browserSync.
158+
159+
### 'production'
160+
The production process is very similar to the default.
161+
162+
The JS build process is
163+
different: it will create an uglified version for a lighter file and faster
164+
browser performance.
165+
166+
The CSS does not need sourcemaps for debugging (as debugging is unnecesary in
167+
the production environment), and so they are not created.
168+
169+
The difference of copying the `index.html` and `public` files is only in the
170+
destination directory `dist`.
171+
172+
A server is connected to show files in the `dist` directory and browserSync
173+
initialized. No watching and reloading tasks are used in production.
174+
175+
## App Context
176+
### Creation
177+
You can recreate the behavior of this app by installing its corresponding
178+
packages individually. Packages were managed with `npm`. The app was created
179+
from scratch in a C9 environment, with a 'blank' template.
180+
181+
1. npm install -g gulp
182+
2. npm install -g jest
183+
3. npm init
184+
4. npm install --save react react-dom
185+
5. npm install --save-dev babel-cli babel-preset-env babel-preset-react
186+
6. npm install --save-dev pump
187+
7. npm install --save-dev gulp
188+
8. npm install --save-dev gulp-sass
189+
9. npm install --save-dev browser-sync
190+
10. npm install --save-dev gulp-sourcemaps
191+
11. npm install --save-dev gulp-uglify
192+
12. npm install --save-dev gulp-clean-css
193+
13. npm install --save-dev gulp-html-replace
194+
14. npm install --save-dev gulp-connect
195+
15. npm install --save-dev vinyl-source-stream
196+
16. npm install --save-dev browserify
197+
17. npm install --save-dev watchify
198+
18. npm install --save-dev gulp-streamify
199+
19. npm install --save-dev babelify
200+
20. npm install --save-dev gulp-concat
201+
21. npm install --save-dev babel-jest
202+
22. npm install --save-dev jest
203+
23. npm install --save-dev jest-cli
204+
24. npm install --save-dev enzyme
205+
25. npm install --save-dev enzyme-adapter-react-16
206+
207+
### References
208+
* [Gettin started with React](https://reactjs.org/docs/add-react-to-an-existing-app.html#installing-react)
209+
* [Getting started with Babel](https://babeljs.io/docs/setup/#installation)
210+
* [Getting started with Gulp](https://css-tricks.com/gulp-for-beginners/)
211+
* [Easier gulpfile debugging with pump](https://www.npmjs.com/package/pump)
212+
* [Building React applications with Gulp and Browserify](https://tylermcginnis.com/react-js-tutorial-pt-2-building-react-applications-with-gulp-and-browserify/)
213+
* [Display and reload the app with Browsersync](https://browsersync.io/)
214+
* [Getting started with Jest](https://facebook.github.io/jest/docs/en/getting-started.html)
215+
* [Expand Jest test suite with Enzyme](http://airbnb.io/enzyme/)
216+
* [Color pallete creation with coolors.co](https://coolors.co/)

0 commit comments

Comments
 (0)