Guide: the create-app script in detail

Inside the package.json you will find the script "create-app", which is a very good starting point for creating your first neo.mjs app. You can run it inside the root folder of the neo.mjs repository like this:

npm run create-app

We would like to shed some light on the internals of this process to show you how to:

  1. Create an app using the script
  2. Change the name of your app
  3. Change the theme(s) of your app
  4. Create an app manually
  5. Remove an app you no longer need
  6. Enhancing the script (feature request)

1) After running the script, you will get asked to enter the name of your app (defaults to MyApp)

Afterwards you will get asked if you want to use the neo-theme-dark, neo-theme-light or both:

This is pretty much it. You will see a new folder under neo/apps with the lowercase version of your app name.
Hint: We recommend to stick to alphabetic characters for your app name.

You can see the code of the script in neo/buildScripts/createApp.js

The script will check, if neo/buildScripts/webpack/development/json/myApps.json exists.
The same will happen for neo/buildScripts/webpack/production/ (sticking to dev from here on, it is 1:1 for prod)

In case the file does not exist, neo/buildScripts/webpack/development/json/myApps.template.json will get consumed to generate it.

{
    "bodyTag": "",
    "buildFolder": "../../../dist/development",
    "environment": "development",
    "mainInput": "./src/Main.mjs",
    "mainOutput": "main.js",

    "workers": {
        "data": {
            "input": "./src/worker/Data.mjs",
            "output": "dataworker.js"
        },
        "vdom": {
            "input": "./src/worker/VDom.mjs",
            "output": "vdomworker.js"
        }
    },

    "apps": {
        "RealWorld": {
            "input": "myApps/RealWorld.mjs",
            "output": "/apps/realworld/",
            "title": "RealWorld"
        }
    }
}

At this point, the RealWorld demo app is already included here to give you an example of how to create an neo.mjs app. The docs app is a neo.mjs app as well (and probably the better starting point.

The .../json/myApps.json files as well as the content inside the neo/apps folder is added to the .gitignore.

To generate the index.html file for your app, neo/buildScripts/webpack/index.ejs will get consumed.
We have an open ticket to enhance this file: #134, please let us know in case this is important for you!

2) Change the name of your app

  1. Change the keys inside the .../json/myApps.json files (inside the apps object)
  2. Rename the app folder to the lowercase version of your new app name
  3. Open the app.mjs file inside your app folder and adjust the appPath & name
  4. Open the index.html file inside your app folder and adjust the appPath
  5. Open the MainContainer.mjs file inside your app folder and adjust the className
  6. Although this process feels like an edge-case, it could get automated with a new script.
    Feel free to open a feature request ticket in case this feels important for you!

3) Change the theme(s) of your app

Open the index.html file inside your app folder and adjust the Neo.config => themes

  1. The default value is themes: ['neo-theme-light', 'neo-theme-dark'], so not using the config includes both themes
  2. themes: ['neo-theme-dark'] => include only the dark theme
  3. themes: ['neo-theme-light'] => include only the light theme
  4. themes: ['neo-theme-dark', 'neo-theme-light'] => include both themes and use the dark theme as the default one.

4) Create an app manually

This process is similar to changing the app name.

  1. Copy an existing app folder into neo/apps and use the new lowercase app name as the folder name
  2. Follow the steps in 3)
  3. Add your new app into the .../json/myApps.json files

5) Remove an app you no longer need

  1. Delete your app folder inside neo/apps
  2. Remove the entries inside the .../json/myApps.json files.
    In case this was your only app, you can delete the the .../json/myApps.json files instead.

6) Enhancing the script (feature request)

We do have an open feature request ticket for creating an npx script, which would allow to create neo apps outside the neo repository root folder. Please take a look at: #90