Skip to content

Commit fd11cb3

Browse files
tripheo0412tripheo0412
committed
update READ.ME
1 parent ae044f7 commit fd11cb3

File tree

4 files changed

+370
-4
lines changed

4 files changed

+370
-4
lines changed

‎README.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -240,10 +240,10 @@ In-progress
240240
</p>
241241

242242
- Login to CircleCI, click on add project -> set up project -> start building -> add manually
243-
- Go back to the main dashboard -> jobs -> click on the setting of your project -> environment variable -> add variable. Then add all the 6 ENV that we just got. After this, you should get something like this:
243+
- Go back to the main dashboard -> jobs -> click on the setting of your project -> environment variable -> add variable. Then add all the 7 ENV that we just got. After this, you should get something like this:
244244

245245
<p align='center'>
246-
<img src='https://raw.githubusercontent.com/tripheo0412/create-gatsby-web/master/assets/images/circleci-env.png' width='600' alt='CircleCI ENV'>
246+
<img src='https://raw.githubusercontent.com/tripheo0412/create-gatsby-web/master/assets/images/circleci-env1.png' width='600' alt='CircleCI ENV'>
247247
</p>
248248

249249
- Voila! Pat your back because you have done a great job 👏

‎assets/images/circleci-env.png renamed to ‎assets/images/circleci-env1.png

File renamed without changes.

‎templates/javascript/src/README.md

Lines changed: 365 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,365 @@
1+
# Create Gatsby Web [![Node Version](https://img.shields.io/badge/Node->=10-339933.svg?style=flat&logo=Node.js)]() [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat&logo=Read-The-Docs)](https://github.com/tripheo0412/create-gatsby-web/blob/master/LICENSE) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-green.svg)](https://github.com/tripheo0412/create-gatsby-web/blob/master/CONTRIBUTING.md)
2+
3+
Bootstrap a Gatsby Web with pre configured development utilities, SEO optimized, ready support for CI/CD pipeline and CMS.
4+
5+
- [Creating a Gatsby Web](#creating-a-gatsby-web) – How to create a new Gatsby web.
6+
- [Connecting CI/CD](#setup-ci-cd) - How to get CI/CD up and running.
7+
- [Setup CMS webhook](#setup-cms-webhook) - How to set webhook from CMS to CircleCI pipeline.
8+
9+
Create Gatsby Web works on macOS, Windows, and Linux.<br>
10+
If something doesn’t work, please [file an issue](https://github.com/tripheo0412/create-gatsby-web/issues/new).<br>
11+
If you have questions or need help, please email me at [[email protected]](mailto:[email protected]).
12+
13+
## Quick Overview
14+
15+
```sh
16+
npx create-gatsby-web
17+
cd <your-project-name>
18+
npm run develop/ yarn develop
19+
```
20+
If you've previously installed `create-gatsby-web` globally via `npm install -g create-gatsby-web`, we recommend you uninstall the package using `npm uninstall -g create-gatsby-web` to ensure that npx always uses the latest version.
21+
22+
_([npx](https://medium.com/@maybekatz/introducing-npx-an-npm-package-runner-55f7d4bd282b) comes with npm 5.2+ and higher, see [instructions for older npm versions](https://gist.github.com/gaearon/4064d3c23a77c74a3614c498a8bb1c5f))_
23+
24+
Your site is now running at `http://localhost:8000`!
25+
26+
_Note: You'll also see a second link: _`http://localhost:8000/___graphql`_. This is a tool you can use to experiment with querying your data. Learn more about using this tool in the [Gatsby tutorial](https://www.gatsbyjs.org/tutorial/part-five/#introducing-graphiql)._<br>
27+
When you’re ready to deploy to production, create a minified bundle with `npm run build/ yarn build`.
28+
29+
<!-- to do add gif how to use -->
30+
31+
### Get Started Immediately
32+
33+
You **don’t** need to install or configure tools.<br>
34+
They are preconfigured so that you can focus on the code. However, all configuration files are exposed so you can customize them whenever you need.
35+
36+
Create a project, and you’re good to go!
37+
38+
### CI/CD pipeline support out-of-the-box
39+
40+
You **just** need to sign up for services, get access tokens and connect your services and the rest is handle my create-gatsby-web<br>
41+
Integrated with scripts to provide real **develop-staging-production** experience.
42+
43+
Learn more [here](#user-guide)
44+
45+
### CMS support
46+
47+
Pre built webhooks support for CMS, you can configure your CMS to call to CircleCI webhooks. CircleCI is already pre configured run CI/CD job if being call by this webhook.<br>
48+
No more broken deployment if client makes a mistake!
49+
50+
Learn more [here](#user-guide)
51+
52+
## Creating a Gatsby Web
53+
54+
**You’ll need to have Node 10 or later version on your local development machine** (but it’s not required on the server). You can use [nvm](https://github.com/creationix/nvm#installation) (macOS/Linux) or [nvm-windows](https://github.com/coreybutler/nvm-windows#node-version-manager-nvm-for-windows) to switch Node versions between different projects.
55+
56+
To create a new web, you may choose one of the following methods:
57+
58+
### npx
59+
60+
```sh
61+
npx create-gatsby-web
62+
```
63+
64+
_([npx](https://medium.com/@maybekatz/introducing-npx-an-npm-package-runner-55f7d4bd282b) is a package runner tool that comes with npm 5.2+ and higher, see [instructions for older npm versions](https://gist.github.com/gaearon/4064d3c23a77c74a3614c498a8bb1c5f))_
65+
66+
It will generate the the initial project structure inside the current folder.<br>
67+
68+
## Template structure
69+
```
70+
├── .circleci
71+
│ └── config.yml
72+
├── .storybook
73+
│ ├── addons.js
74+
│ ├── config.js
75+
│ └── webpack.config.js
76+
├── config
77+
│ └── testing
78+
│ ├── setupTests.js
79+
│ └── __ mocks __
80+
│ ├── file-mock.js
81+
│ ├── gatsby.js
82+
│ └── styleMock.js
83+
├── node_modules
84+
├── src
85+
│ ├── images
86+
│ ├── pages
87+
│ │ ├── index.jsx/tsx
88+
│ │ └── your_page
89+
│ │ └── index.jsx/tsx
90+
│ └── components
91+
│ ├── seo
92+
│ │ └── index.jsx/tsx
93+
│ └── < your component >
94+
│ ├── index.jsx/tsx
95+
│ ├── __ stories __
96+
│ │ └── your_component.stories.jsx/tsx
97+
│ └── __ tests __
98+
│ └── your_component.test.jsx/tsx
99+
├── tasks
100+
│ └── deployment
101+
│ ├── gatsby-deploy-end.sh
102+
│ ├── gatsby-deploy-start.sh
103+
│ ├── storybook-deploy-end.sh
104+
│ └── storybook-deploy-start.sh
105+
├── .eslintignore
106+
├── .eslintrc.js
107+
├── .gitignore
108+
├── .huskyrc.json
109+
├── .lintstagedrc.json
110+
├── .prettierignore
111+
├── .prettierrc
112+
├── gatsby-browser.js
113+
├── gatsby-config.js
114+
├── gatsby-node.js
115+
├── gatsby-ssr.js
116+
├── jest-preprocess.js
117+
├── jest.config.js
118+
├── LICENSE
119+
├── loadershim.js
120+
├── README.md
121+
├── package.json
122+
├── tsconfig.json -- only available on typescript template
123+
└── yarn.lock/package-lock.json
124+
```
125+
126+
1. **`./circleci`**: This directory contains CircleCI configuration file. Note that there are 4 type of jobs: preview-staging-release-webhook
127+
128+
2. **`.storybook/`**: This directory contains all the configuration files for Storybook.
129+
130+
3. **`./config/testing`**: This directory contains all the MOCK configuration files for Jest testing.
131+
132+
4. **`./node_modules`**: This directory contains all of the modules of code that your project depends on (npm packages) are automatically installed.
133+
134+
5. **`./src`**: This directory will contain all of the code related to what you will see on the front-end of your site (what you see in the browser) such as your site header or a page template. `src` is a convention for “source code”.
135+
136+
6. **`.eslintignore`**: This file tells eslint which files it should not track.
137+
138+
7. **`.eslintrc.js`**: Eslint configuration file.
139+
140+
8. **`.gitignore`**: This file tells git which files it should not track / not maintain a version history for.
141+
142+
8. **`.huskyrc.json`**: Husky configuration file. Already setup with a pre git commit hooks.
143+
144+
9. **`.lintstagedrc.json`**: Lint-staged configuration file. Already setup to auto lint and format code before commit.
145+
146+
10. **`.prettierignore`**: This file tells prettier which files it should not track.
147+
148+
11. **`.prettierrc`**: This is a configuration file for [Prettier](https://prettier.io/). Prettier is a tool to help keep the formatting of your code consistent.
149+
150+
12. **`gatsby-browser.js`**: This file is where Gatsby expects to find any usage of the [Gatsby browser APIs](https://www.gatsbyjs.org/docs/browser-apis/) (if any). These allow customization/extension of default Gatsby settings affecting the browser.
151+
152+
13. **`gatsby-config.js`**: This is the main configuration file for a Gatsby site. This is where you can specify information about your site (metadata) like the site title and description, which Gatsby plugins you’d like to include, etc. (Check out the [config docs](https://www.gatsbyjs.org/docs/gatsby-config/) for more detail). SEO component already preconfigure, only production deployment will get index by Google bots all preview and staging will have **noindex** meta tag.
153+
154+
14. **`gatsby-node.js`**: This file is where Gatsby expects to find any usage of the [Gatsby Node APIs](https://www.gatsbyjs.org/docs/node-apis/) (if any). These allow customization/extension of default Gatsby settings affecting pieces of the site build process.
155+
156+
15. **`gatsby-ssr.js`**: This file is where Gatsby expects to find any usage of the [Gatsby server-side rendering APIs](https://www.gatsbyjs.org/docs/ssr-apis/) (if any). These allow customization of default Gatsby settings affecting server-side rendering. Preconfigured to convert stylesheet inline to link, preventing too long head which prevent Facebook, Twitter ... scraping data.
157+
158+
16. **`jest-preprocess.js`**: This file contains babel options to build gatsby project for Jest testing
159+
160+
17. **`jest.config.js`**: This file contains all of Jest configurations.
161+
162+
18. **`LICENSE`**: This boilerplate is licensed under the MIT license.
163+
164+
19. **`loadershim.js`**: This files contains loader setting for Jest.
165+
166+
20. **`package.json`**: A manifest file for Node.js projects, which includes things like metadata (the project’s name, author, etc). This manifest is how npm knows which packages to install for your project.
167+
168+
21. **`README.md`**: A text file containing useful reference information about your project.
169+
170+
22. **`tsconfig.json`**: This file contains all of typescript configurations for type checking.
171+
172+
23. **`yarn.lock/package-lock.json`** (See `package.json` below, first). This is an automatically generated file based on the exact versions of your npm dependencies that were installed for your project. **(You won’t change this file directly).**
173+
174+
All configurations are exposed and predefined folder structures, just write codes, no need to config<br>
175+
Once the installation is done, you can start develop right away!
176+
177+
Inside the newly created project, you can run some built-in commands:
178+
179+
### `npm run develop` or `yarn develop`
180+
181+
Runs the app in development mode.<br>
182+
Your site is now running at `http://localhost:8000`!
183+
184+
_Note: You'll also see a second link: _`http://localhost:8000/___graphql`_. This is a tool you can use to experiment with querying your data. Learn more about using this tool in the [Gatsby tutorial](https://www.gatsbyjs.org/tutorial/part-five/#introducing-graphiql)._
185+
186+
The page will automatically reload if you make changes to the code.<br>
187+
You will see the build errors and lint warnings in the console.
188+
189+
### `npm run build` or `yarn build`
190+
191+
Builds the app for production to the `public` folder.<br>
192+
It correctly bundles React in production mode and optimizes the build for the best performance.
193+
194+
The build is minified and the filenames include the hashes.<br>
195+
196+
Your app is ready to be deployed.
197+
198+
### `npm run storybook` or `yarn storybook`
199+
200+
Runs storybook in development mode.<br>
201+
Storybook live at `http://localhost:6006`!
202+
203+
### `npm run test` or `yarn test`
204+
205+
Run all of your test.
206+
207+
### `npm run test:watch` or `yarn test:watch`
208+
209+
Runs the test watcher in an interactive mode.<br>
210+
211+
## User Guide
212+
213+
### CLI
214+
<p align='center'>
215+
<img src='https://raw.githubusercontent.com/tripheo0412/create-gatsby-web/master/assets/images/help-menu.png' width='600' alt='Help Menu'>
216+
</p>
217+
218+
### Setup CI CD
219+
**Video tutorial**
220+
In-progress
221+
222+
**Prerequisites**
223+
- Github/CircleCI/Netlify account, we only need free version!
224+
- Github [personal access token](https://github.com/settings/tokens) for CircleCI reporting deployment to Pull Request and Github Deployment, note down the token as ```GITHUB_DEPLOYMENTS_TOKEN=<the-token>```.
225+
- Netlify **development** [personal access token](https://app.netlify.com/user/applications?&_ga=2.114107908.208815282.1582632982-167014225.1582120451#personal-access-tokens) for CircleCI to deploy preview and staging (this one belongs to Dev team Netlify's account). Note down the token as ```NETLIFY_ACCESS_TOKEN=<the-token>```. This is your staging website.
226+
- Netlify **production** [personal access token](https://app.netlify.com/user/applications?&_ga=2.114107908.208815282.1582632982-167014225.1582120451#personal-access-tokens) for CircleCI to deploy production (this one belongs to Client Netlify's account - if you owned the project then development access token is enough). Note down the token as ```NETLIFY_CLIENT_ACCESS_TOKEN=<the-token>```. This is your production website.
227+
228+
229+
**How to**
230+
- Upload project to Github's repo, if you want to use CircleCI for free, Github's repo must be **public**.
231+
- Install LighthouseCI via this [LINK](https://github.com/apps/lighthouse-ci), let LighthouseCI access your project repo, note down the TOKEN provided on the authorization confirmation page as ```LHCI_GITHUB_APP_TOKEN=<the-TOKEN>```.
232+
- Run ```yarn build/ npm run build```, you will get Gatsby built **public** folder in the root directory.
233+
- Run ```yarn build-storybook/ npm run build-storybook```, you will get Storybook built **build-storybook** folder in the root directory.
234+
- Login to **Dev team** Netlify, upload the **public** folder via the image below **(DO NOT USE new site from GIT)**, after upload you should get new project deployment in Netlify, click on it and go to site settings, note down the API ID as ```NETLIFY_SITE_ID_STAGING=<the-API-ID >```.
235+
- Still in **Dev team** Netlify, upload the **build-storybook** folder via the image below **(DO NOT USE new site from GIT)**, after upload you should get storybook deployment in Netlify, click on it and go to site settings, note down the API ID as ```NETLIFY_SITE_ID_STORYBOOK=<the-API-ID >```.
236+
- Login to **Client** Netlify, upload the **public** folder via the image below **(DO NOT USE new site from GIT)**, after upload you should get new project deployment in Netlify, click on it and go to site settings, note down the API ID as ```NETLIFY_SITE_ID_RELEASE=<the-API-ID >```.
237+
238+
<p align='center'>
239+
<img src='https://raw.githubusercontent.com/tripheo0412/create-gatsby-web/master/assets/images/netlify-upload.png' width='600' alt='Netlify Upload'>
240+
</p>
241+
242+
- Login to CircleCI, click on add project -> set up project -> start building -> add manually
243+
- Go back to the main dashboard -> jobs -> click on the setting of your project -> environment variable -> add variable. Then add all the 7 ENV that we just got. After this, you should get something like this:
244+
245+
<p align='center'>
246+
<img src='https://raw.githubusercontent.com/tripheo0412/create-gatsby-web/master/assets/images/circleci-env1.png' width='600' alt='CircleCI ENV'>
247+
</p>
248+
249+
- Voila! Pat your back because you have done a great job 👏
250+
251+
### Setup CMS webhook
252+
**Video tutorial**
253+
In-progress
254+
255+
**Prerequisites**
256+
- CircleCI [personal access token](https://circleci.com/docs/2.0/managing-api-tokens/) for CMS to call CircleCi webhooks. Note down the token as ```CIRCLE-TOKEN=<the-token>```.
257+
- CMS account, recommended [Contentful](https://www.contentful.com/)
258+
- Connection keys from CMS, if you use Contentful, click on settings -> API keys -> Content delivery/preview tokens -> Add API key. Note down as:
259+
260+
```
261+
CONTENTFUL_SPACE_ID=<the-Space-ID>
262+
CONTENTFUL_ACCESS_TOKEN=<the-Content-Delivery-API-access token>
263+
```
264+
265+
**How to** (example with Contentful - similar to other CMS)
266+
267+
1. **Setup Contentful**
268+
- Create a **.env** in project root directory, put this in the .env file:
269+
```
270+
CONTENTFUL_SPACE_ID=<the-Space-ID>
271+
CONTENTFUL_ACCESS_TOKEN=<the-Content-Delivery-API-access token>
272+
```
273+
- Run ```yarn add gatsby-source-contentful / npm install --save gatsby-source-contentful```
274+
- Navigate to **gatsby-config**, uncomment the block of code:
275+
```
276+
/***** REMOVE COMMENT TO ENABLE CONTENTFUL CMS
277+
{
278+
resolve: `gatsby-source-contentful`,
279+
options: {
280+
spaceId: process.env.CONTENTFUL_SPACE_ID,
281+
accessToken: process.env.CONTENTFUL_ACCESS_TOKEN,
282+
},
283+
},
284+
******/
285+
```
286+
- Login to CircleCI, main dashboard -> jobs -> click on the setting of your project -> environment variable -> add variable. Then add your CONTENTFUL_SPACE_ID and CONTENTFUL_ACCESS_TOKEN.
287+
288+
2. **Setup webhook**
289+
290+
__Webhook for staging website__
291+
- Login to Contentful, settings -> webhooks -> add webhooks
292+
- Details -> name ```Trigger CircleCi Build Develop Branch```
293+
- Details -> URL -> POST -> ```https://circleci.com/api/v2/project/github/<org-name-or-your-account-name>/<repo-name>/pipeline```
294+
- Triggers -> Select specific triggering events -> tick all Publish + Unpublish
295+
- Headers -> add custom header -> Name: ```Circle-Token``` -> Value: ```<the-token-value>```
296+
- Content type -> application/json
297+
- Payload -> Customize the webhook payload:
298+
```
299+
{
300+
"branch": "develop",
301+
"parameters": {
302+
"trigger": false,
303+
"cms-develop": true
304+
}
305+
}
306+
```
307+
- Click save, voila! you got the **staging** webhook setup. Everytime there is change in contentful, the webhook will trigger CircleCI to run the pipeline and deploy the new content.
308+
309+
__Webhook for production website__
310+
- Login to Contentful, settings -> webhooks -> add webhooks
311+
- Details -> name ```Trigger CircleCi Build Master Branch```
312+
- Details -> URL -> POST -> ```https://circleci.com/api/v2/project/github/<org-name-or-your-account-name>/<repo-name>/pipeline```
313+
- Triggers -> Select specific triggering events -> tick all Publish + Unpublish
314+
- Headers -> add custom header -> Name: ```Circle-Token``` -> Value: ```<the-token-value>```
315+
- Content type -> application/json
316+
- Payload -> Customize the webhook payload:
317+
```
318+
{
319+
"branch": "master",
320+
"parameters": {
321+
"trigger": false,
322+
"cms-master": true
323+
}
324+
}
325+
```
326+
- Click save, voila! you got the **production** webhook setup. Everytime there is change in contentful, the webhook will trigger CircleCI to run the pipeline and deploy the new content.
327+
328+
329+
## Philosophy
330+
331+
- **All exposed:** All configurations are exposed. You have total control of your project settings.
332+
333+
- **No Configuration Required:** You don't need to configure anything. A reasonably good configuration of both development and production builds are handled for you, so you can focus on writing code.
334+
335+
- **CI/CD pipeline ready:** You can setup your own CI/CD pipeline with just a few steps.
336+
337+
- **CMS support** Pre built webhooks support made CMS integration easy.
338+
339+
## What’s Included?
340+
341+
Your environment will have everything you need to build a modern Gatsby web:
342+
343+
- 🏎 React, Gatsby, JSX, ES6, TypeScript syntax support.
344+
- 🏆 CI/CD ready with CircleCI and Netlify.
345+
- 🤝 Out-of-the-box webhooks support for CMS.
346+
- 💻 Language extras beyond ES6 like the object spread operator.
347+
- 👌 Autoprefixed CSS, so you don’t need `-webkit-` or other prefixes.
348+
- 💎 Rich utilities with Eslint, Prettier, Husky and Lint-staged built-in.
349+
- 🛡 A fast interactive unit test runner with built-in support for coverage reporting.
350+
- ✅ A live development server that warns about common mistakes.
351+
- 🕵️‍♂️ A build script to bundle JS, CSS, and images for production, with hashes and sourcemaps.
352+
353+
The tradeoff is that **these are a lot of configuration files**. But they are all pre-configured and we have a detail explaination [here](#template-structure)
354+
355+
## Contributing
356+
357+
We'd love to have your helping hand on `create-gatsby-web`! See [CONTRIBUTING.md](CONTRIBUTING.md) for more information on what we're looking for and how to get started.
358+
359+
## Credits
360+
361+
This project exists thanks to all the people who [contribute](CONTRIBUTING.md).<br>
362+
363+
## License
364+
365+
Create Gatsby Web is open source software [licensed as MIT](https://github.com/tripheo0412/create-gatsby-web/blob/master/LICENSE).

0 commit comments

Comments
 (0)