docs(articles): getting started #354

Francois-Esquire · 2020-10-20T23:27:10Z

Getting started guide for beginners. The article connects the dots between the ecosystem and the runtime.

Description

The article starts with creating a module and moves on to other topics with One App and Holocron.

Types of Changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to not work as expected)
Documentation (adding or updating documentation)
Dependency update

Checklist:

My change requires a change to the documentation and I have updated the documentation accordingly.
These changes should be applied to a maintenance branch.
This change requires cross browser checks.
Performance tests should be ran against the server prior to merging.
This change impacts caching for client browsers.
This change impacts HTTP headers.
This change adds additional environment variable requirements for One App users.
I have added the Apache 2.0 license header to any new files created.

What is the Impact to Developers Using One App?

Documentation

github-actions · 2020-10-20T23:30:14Z

📊 Bundle Size Report

file name	size on disk	gzip
app.js	276.2KB	82.4KB
runtime.js	15KB	5.4KB
vendors.js	117.4KB	36.4KB
app~vendors.js	392.2KB	103.6KB
service-worker-client.js	17KB	5.2KB
legacy/app.js	291.4KB	85.6KB
legacy/runtime.js	15KB	5.4KB
legacy/vendors.js	172.8KB	47.1KB
legacy/app~vendors.js	407.6KB	106.2KB
legacy/service-worker-client.js	17.5KB	5.4KB

Generated by 🚫 dangerJS against c6536d7

JamesSingleton · 2020-10-22T19:37:55Z

docs/articles/Getting-Started.md

+```bash
+export NODE_ENV=development
+
+npx -p yo -p @americanexpress/generator-one-app-module \\


Why break this onto a separate line?

It's a pretty long command and breaks flex positioning in mobile devices.

🤔 but when it gets put to the docs it isn't a simple copy and paste

Honestly, breaking it up like this is a little confusing. I suspect many would think these 2 lines are separate commands

If putting it on one line would make it less confusing, I'm all for it. Will update

Updated in 789f657

JAdshead

Good start, i think we might want to focus on the micro-front end part then reference the recipes for everything else such as styling.

JAdshead · 2020-10-22T20:40:15Z

docs/articles/Getting-Started.md

+### Generating a Module
+
+The first step to get started with One App is to generate a Holocron module.
+There are two different Holocron module types, root and child module. Let us


we should explain what the difference is between root and child module

i'd love if we could add images to describe this

We can plan to add images later, I agree would be so helpful!

docs/articles/Getting-Started.md

JAdshead · 2020-10-22T20:58:19Z

docs/articles/Getting-Started.md

+When `one-app-runner` is fully loaded and running, we can navigate to `http://localhost:3000`
+and view our Holocron module in the browser. In another terminal window you can run
+
+```bash
+npm run watch:build


Suggested change

When `one-app-runner` is fully loaded and running, we can navigate to `http://localhost:3000`

and view our Holocron module in the browser. In another terminal window you can run

```bash

npm run watch:build

When `one-app-runner` is fully loaded and running, we can navigate to `http://localhost:3000`

and view our Holocron module in the browser.

```suggestion

> It can take a few minutes when `one-app-runner` starts for the first time.

Open another terminal window and run:

npm run watch:build

Good. suggestion, I will be adding this manually.

updated 789f657

docs/articles/Getting-Started.md

JAdshead · 2020-10-22T21:00:36Z

docs/articles/Getting-Started.md

+
+```bash
+npm run build
+```


Suggested change

```bash

npm run build

```

You can use also build the module outside of watch mode:`

```bash

npm run build

I will add this manually.

I've added these

nellyk · 2020-10-23T11:55:04Z

docs/articles/Getting-Started.md

+## 📖 Table of Contents
+* [Generating a Module](#generating-a-module)
+* [Running One App](#running-one-app)
+* [Adding CSS Styles](#adding-css-styles)


i really like how you've broken this down into different sections

nellyk · 2020-10-23T11:56:19Z

docs/articles/Getting-Started.md

+* [Creating Routes](#creating-routes)
+* [Module State and Data](#module-state-and-data)
+* [Configuring One App](#configuring-one-app)
+* [Development](#development)


Maybe we should be more specific about this, what do you think? Setting up your development environment

I totally agree that this section is bare compared to the rest, I'll update it

nellyk · 2020-10-23T12:49:50Z

docs/articles/Getting-Started.md

+npm run build
+```
+
+When ready to publish to production, make sure to set `NODE_ENV=production` before building.


should we mention why here?

Maybe this should be in a blockquote

Good points, I will update

nellyk · 2020-10-23T12:59:01Z

docs/articles/Getting-Started.md

+  "name": "my-module",
+  "one-amex": {
+    "bundler": {
+      "webpackConfigPath": "webpack.config.js"


Should we recommend webpackConfigPath for the first setup

@nellyk Agree.. a custom webpack config is usually a feature for advanced users and not necessarily required when you are just getting started

Good point on that, I wanted readers to know that it is possible, however as you both mentioned, it is an advanced feature.

infoxicator · 2020-10-23T13:45:46Z

docs/articles/Getting-Started.md

+  "name": "my-module",
+  "one-amex": {
+    "bundler": {
+      "webpackConfigPath": "webpack.config.js"


@nellyk Agree.. a custom webpack config is usually a feature for advanced users and not necessarily required when you are just getting started

infoxicator · 2020-10-23T13:48:57Z

docs/articles/Getting-Started.md

+>
+> [Adding Styles Recipe](../recipes/adding-styles)
+
+### Creating Routes


I think we should adjust the order of this section to be before adding styles... it would be ideal if you could continue from the previous step, then show developers how to add a second module locally and load it using moduleRoute so it keeps the flow

Additionally we could also show how to load modules with RenderModule from holocron that way we have covered all the possible scenarios for module composition 👍

I actually did want to talk about RenderModule! The reason I left it out was the size of the article was growing... Inthe future, we should think about making a recipe on the different ways to render a module.

About ordering sections, I get where you are coming from when switching the two sections.. the reason I'd want to keep the CSS as the first activity in the module is the ease to set up, a core part of web development (CSS) and direct visual feedback will give readers (especially new to One App or JavaScript) a soft start for the first thing they do in a module. I feel that would segway into more JavaScript heavy sections that follow.

agree with your take @Francois-Esquire since users can still load the webpage from the root, afterwards they can look at adding routes

infoxicator · 2020-10-23T13:52:02Z

docs/articles/Getting-Started.md

+
+We can import the stylesheet into our module and use CSS modules to access the class name
+for each selector by its name. The class names are unique when they are generated which
+avoids unwanted cascading of styles in our document.


We could expand a bit more here to explain that the reason we use cssModules is because modules should be independent and we don't want css from other modules to affect them... hence the unique class name / avoiding collision

I will add a bit to this sentence

infoxicator · 2020-10-23T13:56:05Z

docs/articles/Getting-Started.md

+  );
+}
+
+export default function MyModule({ moduleState = {}, moduleLoadStatus = 'loading' }) {


I don't think we should recommend moduleLoadStatus to check for dataLoading events, after our discussion on on loadModuleData it seems like there is no correlation between the loadModuleStatus and the "Data loading status" we should double check that is the case before suggesting this pattern in our docs

i agree on this

Fair point, will update this

docs/articles/Getting-Started.md

infoxicator · 2020-10-23T14:01:29Z

docs/articles/Getting-Started.md

+
+export default function MyModule() {
+  const { theme } = useSelector(
+    (state) => state.get('config'),


maybe consider this example to load a single config value from the state? for best practices and performance we should recommend avoiding state.ToJS() if possible

docs/articles/Getting-Started.md

infoxicator · 2020-10-23T14:04:54Z

docs/articles/Getting-Started.md

+by creating our first Holocron module, then we will go through a few
+One App essentials to get up and running quickly.
+
+## 📖 Table of Contents


I have seen the CSP is a common pitfall...

What about adding a section for a basic CSP configuration at least explaining that one-app Blocks everything by default and that you won't be able to make any api calls unless you configure your CSP.

This should be explained as one of the main advantages of using one app as a best practice security feature.

I agree with you however CSP is an advanced topic that deserves an article or a set of reference documentation on its own. Another concern with adding a section is it starts to make the document heavy for a getting started guide, no?

yeah we should add it to separate PR and maybe mention the article here once we have the CSP content

10xLaCroixDrinker · 2020-10-23T22:10:37Z

docs/articles/Getting-Started.md

+One App is a web application that combines together multiple experiences into a single,
+cohesive runtime. These experiences, or Holocron modules as we call them empower teams


I think that "micro frontends" would make more sense here than "experiences". Is it really an accurate description to say Holocron modules are experiences? They are more versatile than that

Agree with you, I'll update

10xLaCroixDrinker · 2020-10-23T22:13:18Z

docs/articles/Getting-Started.md

+```bash
+export NODE_ENV=development
+
+npx -p yo -p @americanexpress/generator-one-app-module \\


Honestly, breaking it up like this is a little confusing. I suspect many would think these 2 lines are separate commands

10xLaCroixDrinker · 2020-10-23T22:14:59Z

docs/articles/Getting-Started.md

+npm run build
+```
+
+When ready to publish to production, make sure to set `NODE_ENV=production` before building.


Maybe this should be in a blockquote

10xLaCroixDrinker · 2020-10-26T15:42:39Z

docs/articles/Getting-Started.md

+One App has built in dynamic routing that uses each Holocron module to
+build out the router. There is a special property that we can assign to
+our module `Module.childRoutes` which would allow us to add routes to
+One App. `childRoutes` should be assigned a function that is given


It only needs to be a function when you need to use the store for something, otherwise it can be an array or just a route with or without nested routes

TIL, thank you for sharing that 😄 I'll update the wording.

Co-authored-by: Ruben Casas <ruben@infoxication.net>

Co-authored-by: Jonny Adshead <JAdshead@users.noreply.github.com> Co-authored-by: Ruben Casas <ruben@infoxication.net>

Co-authored-by: Jonny Adshead <JAdshead@users.noreply.github.com>

docs(articles): getting started

8cfdbad

Francois-Esquire requested a review from a team as a code owner October 20, 2020 23:27

Merge branch 'main' into docs/getting-started

a6ba1ff

github-actions bot added the documentation Improvements or additions to documentation label Oct 20, 2020

Mike Tobia and others added 3 commits October 20, 2020 19:35

fix(corrections): getting started

9e7ff87

fix(docs): frontend

821a619

Merge branch 'main' into docs/getting-started

890a3ba

JamesSingleton reviewed Oct 22, 2020

View reviewed changes

fix(title): use header

bf555a9

JAdshead suggested changes Oct 22, 2020

View reviewed changes

nellyk reviewed Oct 23, 2020

View reviewed changes

infoxicator suggested changes Oct 23, 2020

View reviewed changes

10xLaCroixDrinker suggested changes Oct 26, 2020

View reviewed changes

James Singleton and others added 8 commits October 27, 2020 15:24

Merge branch 'main' into docs/getting-started

262ce0d

Merge branch 'main' into docs/getting-started

554125e

Merge branch 'main' into docs/getting-started

d851005

fix(getting-started): selector example

6bc91df

Co-authored-by: Ruben Casas <ruben@infoxication.net>

fix(getting-started): review suggestions

e32575a

Co-authored-by: Jonny Adshead <JAdshead@users.noreply.github.com> Co-authored-by: Ruben Casas <ruben@infoxication.net>

fix(getting-started): add questions

bca0f9f

Co-authored-by: Jonny Adshead <JAdshead@users.noreply.github.com>

fix(feedback): update

3894600

fix(getting-started): add readme

091561d

Francois-Esquire requested review from 10xLaCroixDrinker, infoxicator and JAdshead October 29, 2020 18:49

James Singleton added 2 commits October 29, 2020 12:55

Merge branch 'main' into docs/getting-started

a036763

Merge branch 'main' into docs/getting-started

713f169

docs(getting-started): move to overview

789f657

infoxicator approved these changes Nov 3, 2020

View reviewed changes

nellyk approved these changes Nov 4, 2020

View reviewed changes

Francois-Esquire and others added 2 commits November 10, 2020 14:23

Merge branch 'main' into docs/getting-started

3d357fe

Merge branch 'main' into docs/getting-started

77e7c6a

JamesSingleton approved these changes Nov 10, 2020

View reviewed changes

Francois-Esquire and others added 3 commits November 10, 2020 16:29

Merge branch 'main' into docs/getting-started

0cbb872

Merge branch 'main' into docs/getting-started

5888063

Merge branch 'main' into docs/getting-started

b9ef49e

JAdshead approved these changes Nov 10, 2020

View reviewed changes

Francois-Esquire added 2 commits November 11, 2020 10:02

Merge branch 'main' into docs/getting-started

bf13507

Merge branch 'main' into docs/getting-started

c6536d7

10xLaCroixDrinker approved these changes Nov 12, 2020

View reviewed changes

Francois-Esquire merged commit 68e0641 into main Nov 12, 2020

Francois-Esquire deleted the docs/getting-started branch November 12, 2020 16:02

		One App is a web application that combines together multiple experiences into a single,
		cohesive runtime. These experiences, or Holocron modules as we call them empower teams

docs(articles): getting started #354

docs(articles): getting started #354

Conversation

Francois-Esquire commented Oct 20, 2020 • edited Loading

Description

Types of Changes

Checklist:

What is the Impact to Developers Using One App?

github-actions bot commented Oct 20, 2020 • edited Loading

📊 Bundle Size Report

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

JAdshead left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

infoxicator Oct 23, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

infoxicator Oct 23, 2020 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Francois-Esquire Oct 29, 2020 • edited Loading

Choose a reason for hiding this comment

Francois-Esquire commented Oct 20, 2020 •

edited

Loading

github-actions bot commented Oct 20, 2020 •

edited

Loading

infoxicator Oct 23, 2020 •

edited

Loading

infoxicator Oct 23, 2020 •

edited

Loading

Francois-Esquire Oct 29, 2020 •

edited

Loading