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.
- build-all
- build-all-questions
- build-my-apps
- build-themes
- build-threads
- create-app
- generate-docs-json
- server-start
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 commandThe build-all program is using the -n (noquestions) option. Take a look at the next section for details on those.
- The program starts with a npm install(-l option).
- It builds the themes next (-t option) => build-themes.
- It builds the threads (-w option) => build-threads.
(-w is a shortcut for "workers", since -t was already taken.) - 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
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:
- Pick the -l (npminstall) option:
neo % npm run build-all-questions
> neo.mjs@1.4.14 build-all-questions /Users/Shared/github/neomjs/neo
> node ./buildScripts/buildAll.js -f
neo.mjs buildAll
? Run npm install?: (Use arrow keys)
❯ yes
no - Pick the -e (env) option:
neo.mjs buildAll
? Run npm install?: yes
? Please choose the environment: (Use arrow keys)
❯ all
dev
prod - 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 - 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 - 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
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 commandbuild-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:
- Pick the -e (env) option:
neo % npm run build-my-apps
> neo.mjs@1.4.14 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 - 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
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 commandLet us take a look at the different inquirer steps:
- Pick the -t (themes) option:
neo % npm run build-themes
> neo.mjs@1.4.14 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 - 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 - 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
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 commandLet us take a look at the different inquirer steps:
- Pick the -t (threads) option:
neo % npm run build-threads
> neo.mjs@1.4.14 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 - 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
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 commandLet us take a look at the different inquirer steps:
- Pick the -a (appName) option:
neo % npm run create-app
> neo.mjs@1.4.14 create-app /Users/Shared/github/neomjs/neo
> node ./buildScripts/createApp.js
neo.mjs create-app
? Please choose a name for your neo app: (MyApp) - 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 - 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)- 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://inspect/#workers
Source code: create-app
node ./buildScripts/docs/jsdocx.js
neo.mjs is using jsdoc
to parse code comments and get the input we need for the Docs App. More precisely, our parser is based on:
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
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
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):
I am mostly using the WebStorm IDE web-server instead, which works fine as well.