Skip to content

Latest commit

 

History

History

buildScripts

README.md

Command-Line Interface

In case you want to create an App (workspace) based on neo.mjs, you don't need to clone this repository.
Please take a look at the create-app repository (npx neo-app).

This guide explains the different scripts (programs) which are included inside the package.json.
They are important for working on the framework code base.

You can run each script inside your terminal. E.g.:

npm run build-all

Make sure to call them on the top-level folder (the one containing the package.json).

In case you want to pass program options, please use the node based calls instead. E.g.:

node ./buildScripts/buildAll.js -h

All programs which are using options also have the visual inquirer interface in place.
So it is up to you if you prefer adding the options manually (e.g. for adding them into your own CI),
or selecting them without memorising the shortcuts.

You will notice that most programs are using the -f (framework) option here. The reason is that you can call them inside your neo.mjs workspaces as well, where the framework is included as a node module, but needs to deploy to a top-level dist folder.

Content

  1. build-all
  2. build-all-questions
  3. build-my-apps
  4. build-themes
  5. build-threads
  6. create-app
  7. generate-docs-json
  8. server-start

build-all

node ./buildScripts/buildAll.js -f -n

It is strongly recommended to run this program after each git pull on this repo.

Options:
  -V, --version             output the version number
  -i, --info                print environment debug info
  -e, --env <value>         "all", "dev", "prod"
  -l, --npminstall <value>  "yes", "no"
  -f, --framework          
  -n, --noquestions        
  -p, --parsedocs <value>   "yes", "no"
  -t, --themes <value>      "yes", "no"
  -w, --threads <value>     "yes", "no"
  -h, --help                display help for command

The build-all program is using the -n (noquestions) option. Take a look at the next section for details on those.

  1. The program starts with a npm install(-l option).
  2. It builds the themes next (-t option) => build-themes.
  3. It builds the threads (-w option) => build-threads.
    (-w is a shortcut for "workers", since -t was already taken.)
  4. It parses the docs comments (-p option) => generate-docs-json.

You can disable each step using the program options.

build-all will delegate the env, framework & noquestions options to build-themes & build-threads.

You can use the -e (environment) option in case you want to limit the build either to dist/development or dist/production.

Source code: build-all

build-all-questions

node ./buildScripts/buildAll.js -f

This entry point is running the build-all program without passing options, so we can select them using the inquirer interface.

Let us take a look at the different inquirer steps:

  1. Pick the -l (npminstall) option:
neo % npm run build-all-questions

> [email protected] build-all-questions /Users/Shared/github/neomjs/neo
> node ./buildScripts/buildAll.js -f

neo.mjs buildAll
? Run npm install?: (Use arrow keys)
❯ yes 
  no
  1. Pick the -e (env) option:
neo.mjs buildAll
? Run npm install?: yes
? Please choose the environment: (Use arrow keys)
❯ all 
  dev 
  prod
  1. Pick the -t (themes) option:
neo.mjs buildAll
? Run npm install?: yes
? Please choose the environment: all
? Build the themes? (Use arrow keys)
❯ yes 
  no
  1. Pick the -w (threads) option:
neo.mjs buildAll
? Run npm install?: yes
? Please choose the environment: all
? Build the themes? yes
? Build the threads? (Use arrow keys)
❯ yes 
  no
  1. Pick the -p (parsedocs) option:
neo.mjs buildAll
? Run npm install?: yes
? Please choose the environment: all
? Build the themes? yes
? Build the threads? yes
? Trigger the jsdocx parsing? (Use arrow keys)
❯ yes 
  no

Source code: build-all

build-my-apps

node ./buildScripts/webpack/buildMyApps.js -f

Options:
  -V, --version       output the version number
  -i, --info          print environment debug info
  -a, --apps <value>  "all", "Covid", "RealWorld", "RealWorld2", "SharedCovid", "SharedCovidChart", "SharedCovidGallery",
                      "SharedCovidHelix", "SharedCovidMap", "SharedDialog", "SharedDialog2", "Website"
  -e, --env <value>   "all", "dev", "prod"
  -f, --framework    
  -n, --noquestions  
  -h, --help          display help for command

build-my-apps is very similar to build-threads => App.

In both cases we are parsing worker/App, which will dynamically import all Apps inside the src/app folder and the Docs App and create split chunks for all combinations. This enables you to add multiple Apps on one Page with close to zero overhead in dist/development & dist/production.

The only difference to build-threads => App is that you can limit the generation of the App related index.html files, so it is a little faster.

Let us take a look at the different inquirer steps:

  1. Pick the -e (env) option:
neo % npm run build-my-apps

> [email protected] build-my-apps /Users/Shared/github/neomjs/neo
> node ./buildScripts/webpack/buildMyApps.js -f

neo.mjs buildMyApps
? Please choose the environment: (Use arrow keys)
❯ all 
  dev 
  prod
  1. Pick the -a (apps) option:
neo.mjs buildMyApps
? Please choose the environment: all
? Please choose which apps you want to build: (Press <space> to select, <a> to toggle all, <i> to invert selection)
❯◯ Covid
 ◯ RealWorld
 ◯ RealWorld2
 ◯ SharedCovid
 ◯ SharedCovidChart
 ◯ SharedCovidGallery
 ◯ SharedCovidHelix
(Move up and down to reveal more choices)

Source code: build-my-apps

build-themes

node ./buildScripts/webpack/buildThemes.js -f

Options:
  -V, --version          output the version number
  -i, --info             print environment debug info
  -c, --cssVars <value>  "all", "true", "false"
  -e, --env <value>      "all", "dev", "prod"
  -f, --framework       
  -n, --noquestions     
  -t, --themes <value>   "all", "dark", "light"
  -h, --help             display help for command

Let us take a look at the different inquirer steps:

  1. Pick the -t (themes) option:
neo % npm run build-themes

> [email protected] build-themes /Users/Shared/github/neomjs/neo
> node ./buildScripts/webpack/buildThemes.js -f

neo.mjs buildThemes
? Please choose the themes to build: (Use arrow keys)
❯ all 
  dark 
  light
  1. Pick the -e (env) option:
neo.mjs buildThemes
? Please choose the themes to build: all
? Please choose the environment: (Use arrow keys)
❯ all 
  dev 
  prod
  1. Pick the -c (cssVars) option:
neo.mjs buildThemes
? Please choose the themes to build: all
? Please choose the environment: all
? Build using CSS variables? (Use arrow keys)
  all 
❯ yes 
  no

Source code: build-themes

build-threads

node ./buildScripts/webpack/buildThreads.js -f

Since the default neo.mjs setup is using 3 workers, we have the following 4 threads to build:
"app", "data", "main", "vdom"

Most of the framework code base & the apps you build with it run inside the App Worker,
so most of the time you only need to build the app thread.

Options:
  -V, --version          output the version number
  -i, --info             print environment debug info
  -e, --env <value>      "all", "dev", "prod"
  -f, --framework       
  -n, --noquestions     
  -t, --threads <value>  "all", "app", "data", "main", "vdom"
  -h, --help             display help for command

Let us take a look at the different inquirer steps:

  1. Pick the -t (threads) option:
neo % npm run build-threads

> [email protected] build-threads /Users/Shared/github/neomjs/neo
> node ./buildScripts/webpack/buildThreads.js -f

neo.mjs buildThreads
? Please choose the threads to build: (Use arrow keys)
❯ all 
  app 
  data 
  main 
  vdom
  1. Pick the -e (env) option:
neo.mjs buildThreads
? Please choose the threads to build: all
? Please choose the environment: (Use arrow keys)
❯ all 
  dev 
  prod

Source code: build-threads

create-app

node ./buildScripts/createApp.js

Again: In case you want to create an App (workspace) based on neo.mjs, you don't need to clone this repository.
Please take a look at the create-app repository (npx neo-app).

If you want to create a new Demo App inside the framework repo, using the create-app program makes sense, since you can work on the app & framework code in parallel.

Using the default options, this will generate the following 3 files:

neo
 | - apps
 |    | - myapp
 |    |    | - app.mjs
 |    |    | - config.json
 |    |    | - index.html
 |    |    | - MainContainer.mjs

The program will also add the App config into buildScripts/webpack/json/myApps.json.

"apps": [
    "Docs",
    "MyApp"
]

This file is added inside the .gitignore.
If the file does not exist yet, the program will copy buildScripts/webpack/json/myApps.template.json to create it.

Options:
  -V, --version                   output the version number
  -i, --info                      print environment debug info
  -a, --appName <value>           
  -m, --mainThreadAddons <value>  Comma separated list of AmCharts, AnalyticsByGoogle, HighlightJS, LocalStorage,
                                  MapboxGL, Markdown, Siesta, Stylesheet.
                                  Defaults to Stylesheet
  -t, --themes <value>            "all", "dark", "light"
  -u, --useSharedWorkers <value>  "yes", "no"
  -h, --help                      display help for command

Let us take a look at the different inquirer steps:

  1. Pick the -a (appName) option:
neo % npm run create-app

> [email protected] create-app /Users/Shared/github/neomjs/neo
> node ./buildScripts/createApp.js

neo.mjs create-app
? Please choose a name for your neo app: (MyApp)
  1. Pick the -t (themes) option:
neo.mjs create-app
? Please choose a name for your neo app: MyApp
? Please choose a theme for your neo app: (Use arrow keys)
  neo-theme-dark 
  neo-theme-light 
❯ both
  1. Pick the -m (mainThreadAddons) option:
neo.mjs create-app
? Please choose a name for your neo app: MyApp
? Please choose a theme for your neo app: both
? Please choose your main thread addons: (Press <space> to select, <a> to toggle all, <i> to invert selection)
❯◯ AmCharts
 ◯ AnalyticsByGoogle
 ◯ HighlightJS
 ◯ LocalStorage
 ◯ MapboxGL
 ◯ Markdown
 ◯ Siesta
(Move up and down to reveal more choices)
  1. Pick the -u (useSharedWorkers) option:
neo.mjs create-app
? Please choose a name for your neo app: MyApp
? Please choose a theme for your neo app: both
? Please choose your main thread addons: Stylesheet
? Do you want to use SharedWorkers? Pick yes for multiple main threads (Browser Windows): (Use arrow keys)
  yes 
❯ no

No worries, you can easily change the options after you created your App shell.

E.g. in case you want to add the MapboxGL main thread addon later on, you can add it inside your index.html file:

Object.assign(Neo.config, {
    appPath         : 'apps/myapp/app.mjs',
    basePath        : '../../',
    environment     : 'development',
    mainThreadAddons: ['MapboxGL', 'Stylesheet']
});

Regarding the -u (SharedWorkers) option:
Only use it in case you want to create an App which uses multiple main threads (Browser Windows).
Even in this case I recommend to start without it and switch at the point when your App is ready to connect a second one, since it does make the debugging more complicated.

With normal Workers, you can get console logs & error messages inside your Browser Tab dev tools.
Using SharedWorkers, you need to open a separate Window to inspect them:

chrome:https://inspect/#workers

Source code: create-app

generate-docs-json

node ./buildScripts/docs/jsdocx.js

neo.mjs is using jsdoc

https://github.com/jsdoc/jsdoc

to parse code comments and get the input we need for the Docs App. More precisely, our parser is based on:

https://github.com/onury/jsdoc-x

to get the output in json based format. There are several enhancements around it to polish it for our class system improvements.

Source code: generate-docs-json

server-start

webpack serve -c ./buildScripts/webpack/webpack.server.config.js --open

To open JS modules locally inside your Browser you need a web-server, since importing files is not possible otherwise for security reasons. You could enable this on an OS level, but this is definitely not recommended.

One option is to use

https://github.com/webpack/webpack-dev-server

We are running the server on the repository root folder, since we want to access the apps & examples folders directly for the development mode.

Normally this server does get mapped to the dist folder, which enables hot module replacements for dist/development. Since the neo.mjs development mode runs without any JS builds or transpilations, this is not really needed.

There is a ticket for it (low prio):

neomjs#96

I am mostly using the WebStorm IDE web-server instead, which works fine as well.