HomeGuidesBlueprintsCommunityChangelogAPI ReferenceGet support
Guides

Helix App

Main documentation for Helix - Frontend framework

Prepare

To download and setup Helix App, use the Helix App Boilerplate, see onify/helix-app-boilerplate.

Installation

Create a new file named .npmrc and copy the contents of .npmrc.example into it:

@onify:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=<ONIFY_GITHUB_ACCESS_TOKEN>

Replace <ONIFY_GITHUB_ACCESS_TOKEN> with your Github Personal Access Token. This step is necessary to enable downloading of helix packages.

Before installing packages, please update Onify Helix package version in package.json first. Search for "*" and replace with correct version, eg "1.0.0". Here is and example of package.json with update version:

...
    "@onify/helix-components": "1.0.0",
    "@onify/helix-core": "1.0.0",
    "@onify/helix-pages": "1.0.0",
    "@onify/helix-themes": "1.0.0",
    "@onify/helix-tools": "1.0.0",
...
    "@onify/helix-tests": "1.0.0",
...

Afterwards, navigate to your copy of the helix-app and run the command:

npm i

Upgrade

To download the latest version of helix-app, run the command:

IMPORTANT: Everything in this folder will be overwritten!

Upgrade to latest: npx giget "gh:onify/helix/apps/helix-app" ./ --auth="<ONIFY_GITHUB_ACCESS_TOKEN>" --force --verbose

(Upgrade to specific version: npx giget "gh:onify/helix/apps/helix-app#vX.XX.X" ./ --auth="<ONIFY_GITHUB_ACCESS_TOKEN>" --force --verbose)

NOTE: If you added custom node modules to package.json you need to add them again.

To install new and update modules, run:

npm i

NOTE: If you have issues with your node modules. Try removing package-lock.json and running npm i again.

Environment variables

For development on localhost, create a file called .env with the following content.

HELIX_BASE_URL="/helix"
HELIX_LOGIN_URL="/login"
HELIX_LOGOUT_URL="/logout"
HELIX_ERROR_URL="/helix/error"
HELIX_API_URL='/api/v2'

ONIFY_HUB_API_PATH="/api/v2"
ONIFY_HUB_APP_URL="/"

# --- VARS FOR LOCAL DEVELOPMENT ---
VITE_PORT=5173
VITE_LOCAL_API_TOKEN="***" # Add authentication token to disable redirect to login page
VITE_LOCAL_API_PROXY_TARGET="http://localhost:3000/api/v2"
VITE_LOCAL_API_PROXY_ENDPOINT="/api/v2"

# Uncomment the lines below (remove #) when SSO login flow and proxy API requests should be handled by Helix instead of the legacy app
# This will override the values above since environment variables use the last defined value
#HELIX_API_URL="/helix/api/v2"
#HELIX_LOGIN_URL="/helix/login"
#HELIX_LOGOUT_URL="/helix/logout"
#ONIFY_HUB_API_PATH="/helix/api/v2"
#VITE_LOCAL_API_PROXY_TARGET="http://localhost:8181/api/v2"
#VITE_LOCAL_API_PROXY_ENDPOINT="/helix/api/v2"
#VITE_SSO_CALLBACK_PROXY_ENDPOINT="/helix/sso/callback"

# Config files
VITE_HELIX_SETTINGS_PATH="./config/settings.yml"
VITE_HELIX_ORG_SETTINGS_PATH="./config/settings.org.yml"
VITE_HELIX_PAGES_PATH="./config/pages.yml"
VITE_HELIX_ORG_PAGES_PATH="./config/pages.org.yml"
VITE_HELIX_THEMES_PATH="./config/themes.yml"
VITE_HELIX_ORG_THEMES_PATH="./config/themes.org.yml"
VITE_HELIX_STRINGS_PATH="./config/strings.yml"
VITE_HELIX_ORG_STRINGS_PATH="./config/strings.org.yml"
VITE_HELIX_EMBEDS_PATH="./config/embeds.yml"
VITE_HELIX_ORG_EMBEDS_PATH="./config/embeds.org.yml"

Default port is 5173. It is recommended to use different ports for each instance of helix-app. To do this, change VITE_PORT to the desired, unused port.

Proxy Migration Guide

For detailed instructions on migrating from the legacy proxy mode to the new Helix proxy mode (where Helix handles SSO authentication and API proxying directly), please see the Proxy Migration Guide.

The guide covers:

  • Development environment setup for both legacy and new proxy modes
  • How to enable Helix proxy mode by uncommenting environment variables
  • Production deployment with Docker and nginx
  • Complete authentication flow and troubleshooting

Development

Start app in development mode

To run the app in dev mode, execute the command:

npm run dev

Debugging in VSCode

A running instance of helix app is required.

npm run dev

Open Run and Debug mode by pressing Ctrl + Shift + D In the dropdown menu, select 'Helix App' and press F5 A debugging instance of chrome will be launched Variable values will be available in left pane and may also be checked on mouse hover

Configuration

Pages

Default we will use the pages.org.yml to configure the pages. But this can be changed by copying this file to pages.yml. Here is an example of a custom pages.yml file:

 - name: root # Support for redirect root
  path: /
  redirect: create-ticket

- name: admin-logs
  path: /admin/logs
  import: '@onify/helix-pages'
  component: OAdminLogs

- name: admin-processes
  path: /admin/processes
  import: '@onify/helix-pages'
  component: OAdminProcesses

- name: error404
  authenticate: false
  path: '/:pathMatch(.*)*'
  import: '@onify/helix-pages'
  component: OError404

- name: create-ticket # Support for custom pages
  path: /create-ticket
  import: ../src/custom/pages/create-ticket.vue
  # layout:
  #   import: ../src/custom/layouts/custom-layout.vue # Support for custom layouts

Themes

Default we will use the themes.org.yml to configure the themes. But this can be changed by copying this file to themes.yml. Here is an example of a custom themes.yml file:

- name: legacy
  title: Legacy
  themepack: onify:legacy
  import: '@onify/helix-themes'
  overrides: # Customize a themepack
    vuetify:
      defaults:
        VCard:
          variant: elevated
        VBtn:
          variant: elevated
      theme:
        colors:
          primary: '#6391E2'
          surface: '#FFFFFF'
          on-surface: '#1D1B1E'

- name: light
  title: Light
  themepack: onify:helix
  import: '@onify/helix-themes' # Importing packages are also supported
  #cssExtend: './src/custom/styles/style' # Optional - Support extending css. Recommend not to include `.css/.sass/.scss` file extensions

- name: dark
  title: Dark
  themepack: onify:helix-dark
  import: '@onify/helix-themes'

- name: custom # Supporting for custom themes
  title: Custom
  themepack: custom
  import: './src/custom/themes/custom.js' # Paths are relative to the project root (process.cwd())

Embedded Apps

Building Embedded Apps

Similar to configuring pages for helix-app, we can configure the app to separately build pages for use as embedded applications. To do this, create an embeds.yml file in the config directory.

Here is an example of a custom embeds.yml file:

- name: 'test-dataStore'
  import: '../src/custom/pages/examples/test-dataStore.vue'

- name: 'test-legacyForm'
  import: '../src/custom/pages/examples/test-legacyForm.vue'

- name: 'test-snackbar'
  import: '../src/custom/pages/examples/test-snackbar.vue'

- name: 'test-translations'
  import: '../src/custom/pages/examples/test-translations.vue'

- name: 'test-useBindQueryParams'
  import: '../src/custom/pages/examples/test-useBindQueryParams.vue'

- name: 'test-useLiveSearch'
  import: '../src/custom/pages/examples/test-useLiveSearch.vue'

- name: 'test-validate'
  import: '../src/custom/pages/examples/test-validate.vue'

Afterwards, you can run npm run build:embeds in the terminal to build the apps. The output, by default, will be located under the dist.embeds directory. You should expect to see a file structure with the following format:

.
└── dist.embeds/
    ├── assets
    └── [name]/
        ├── index.html
        └── main.[hash].js

Each app is outputted into a folder with the value of name field specified in the embeds.yml file. Given the embeds.yml config file above, the contents inside the dist.embeds directory should look like:

.
└── dist.embeds/
    ├── assets
    ├── test-dataStore
    ├── test-legacyForm
    ├── test-snackbar
    └── ...

The assets folder contains all the asset files (css, media content, fonts, etc.) that are used and shared between the apps. If you only want to embed one of the apps; you can copy the desired app and assets folders and paste them into the desired location.

Previewing Embedded Apps

Finally, you can preview your embedded apps using the npm run serve:embeds command and then accessing the sites outputted in the terminal.

Testing

Make sure to install all dependencies first:

npm i

A running instance of helix app is required.

npm run dev

Folder structure for test files:

│ …
├ test/
│ ├── pages
│ │ └── … (.spec.js scripts)
│ ├── components (may be supported in the future)
│ │ └── … (.spec.js scripts)
│ ├── fixtures
│ │ └── … (*.json mock data)
│ ├── support
│ │ ├── commands.ts (http intercept commands)
│ │ └── …

Optional environment variables:

ONIFY_TEST_VIDEO - Enables producing video logs after tests. Log files spawn under test/logs directory (default false).
ONIFY_TEST_SCREENSHOT_ON_FAIL- Enables producing screenshot logs after failed tests. Log files spawn under test/logs directory (default false).
ONIFY_TEST_HEADLESS- Enables testing in headless mode (default false).

Once all files are set, you may run tests.

npm run test

Examples

We have some sample references to help you get started. You can find sample pages under the ./src/examples/ directory.

NOTE: The examples are currently a work in progress. If you need any assistance, please contact [email protected].

Deploy

The best way to deploy Onify Helix is via creating a Docker image, see Dockerfile. You can build your image and store it in any container registry.

Build image

Here are instructions on how to build image in GitHub and use GitHub container registry.

  1. Add a action repository secret called ONIFY_GITHUB_ACCESS_TOKEN and use your access token
  2. Check and view example workflows (see below) and copy the ones you want to use

GitHub workflows

  • build_latest.yml(.example) - Build and create image when commiting code to main branch
  • build_branch.yml(.example) - Build and create image when commiting code to any branch (except main)
  • build_release.yml(.example) - Build and create image when tagging (eg. 1.0.0) a commit (used when releasing versions)

Updated about 5 hours ago