Generator

Hex core JS code generator CLI tool.

Usage

In your frontend directory, run the following command.

npx @hex-insights/generator [command] [options]
Copy

See generator --help to see top level options.

The current available commands are

• authentication

  • Adds pages and context for handling user authentication in an app.

• collect-pages

  • Searches an application for all pageinfo files and creates a centralized array of all PageInfo objects. Note that discovery is based on files that are either named pageinfo.tsx? or *.pageinfo.tsx? and object names must be either pageInfo or suffixed with PageInfo.

• generate-app

  • Adds a new app to an existing project.

• generate-model

  • Adds new models to an existing app.

• init

  • Creates a hex.config.js file with default settings for use by this package. Should be run before any other command.

• permissions

  • Generate a static permissions object containing all permissions from the database.

• scaffold

  • Initialize your frontend for the first time. It is recommended to run the init command before running scaffold.

• update-package-versions

  • Updates local package versions with the updates given. Updates all dependent versions as well with patch updates.

  • Example:

    npx @hex-insights/generator update-package-versions \
        -u \
            @hex-insights/core 0.1.0 \
            @hex-insights/forms 0.0.1
    Copy

Frontend Setup Guide

Basic Setup

1. In the project directory, create a frontend directory.

2. Create an .env or .envrc file with at least the following contents:

   export NODE_AUTH_TOKEN="AUTH TOKEN"
   Copy

   Your auth token must have at least the read:packages permissions.

3. Create an .npmrc file in the frontend directory with the following contents:

   @hex-insights:registry=https://npm.pkg.github.com
   //npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}
   Copy

Generating

1. Run the init command:

   npx @hex-insights/generator init
   Copy

   This creates a config file for this package in the project. Make any necessary modifications before continuing.

2. Run the scaffold command:

   npx @hex-insights/generator scaffold -n "<Project Name>" -p "@hex-insights/<project-name>" -r "https://github.com/hex-insights/<project-name>" -d "<App description>" -m <ModelNames...>
   Copy

   Note that the package name (-p) will be used to prefix packages contained in the generated project. For example, the default shared package would be called @hex-insights/<project-name>.shared.

   Note that model names are not required as part of the scaffold command, however including them is recommended as additional handling will be added by default (e.g. routing to hubs).

   The path to the schema file will be added to the generated config file.

3. Generate server-dependent code (with the server running in system mode):

   npm run generate
   Copy

4. Build package types:

   npm run build:types
   Copy

5. Run the application:

   cd packages/portal
   npm start
   Copy

Changes

Adding Models

1. Run the init hub command and pass a list of (space-separated) model names to add:

   npx @hex-insights/generator generate-model -m "<ModelName>"
   Copy

   This will create a hub, utilities, and components for the model. Some generated files contain TODO comments to indicate where action is required, however, the following items provide a clearer guide to taking these actions. Note that the generated output will use the SRSL file if provided, if not provided, the generated output assumes each model has a field called name and includes that as a starting point to serve as a guide. If a model does not have a name field, then additional work is required to remove references to the name field. If using a SRSL file the following items should be close to desired, but may require some modifications. The path to the SRSL file for the project is defined in the hex.config.js file but can be overridden by providing the -s or --schema flag to generate-model.

2. Edit or populate GraphQL query files in packages/shared/src/Utilities/GraphQL/Queries. The detail.fragment.graphql file should be updated so that all necessary fields are included (this fragment is used by the create.graphql, detail.graphql, and update.graphql files ). The index.graphql and select.graphql files may also be updated if desired (or if not using a SRSL file and the model does not have a name field). The delete.graphql and pagination.graphql files do not need to be updated.

3. Generate GraphQL-related code:

   npm run generate
   Copy

   This will, among other things, use the GraphQL query files defined in the previous step to create TypeScript code.

4. Edit or populate form values types for each new model in packages/shared/src/Utilities/Forms/ModelFormValues.

5. Edit or populate form values in the toFormValues function for each new model in packages/shared/src/Utilities/Forms/ModelFormConversion and add handling for any nullable fields in toGQLUpdateInput in the same file.

6. Edit or define form validation functions for each new model in packages/shared/src/Utilities/Forms/ModelFormValidation.

7. Edit or define field format functions for each new model in packages/shared/src/Utilities/Format/ModelAttributeFormat.

8. Edit or define fields for each new model in packges/shared/src/Components/Forms/ModelForms/<ModelName>/Field.tsx and add fields to the create and detail forms for each new model in the Form.tsx file in the same directory.

9. Edit or define order fields and the order field type mapping in packages/shared/src/Utilities/Forms/ModelOrderFormValues for each new model.

10. Edit or define filter field options and type mapping in packages/shared/src/Utilities/Forms/ModelFilterFormValues for each new model.

11. Define standard filters for the model. The values type and initial values go in packages/shared/src/Utilities/Forms/ModelFilterFormValues. The count, reset, and conversion logic goes in packages/shared/src/Utilities/Forms/ModelFilterFormUtils. The components go in packages/shared/src/Components/Forms/ModelFilterForms.

12. Add links to each of the new models' hubs in the hub index page (packages/$app-name/src/Pages/Hubs/IndexPage).

Notes on Rerunning Commands

All files generated by this package begin with a comment that indicates how the file will be treated when rerunning a command. If a file begins with the "hard" generated comment (contains "DO NOT EDIT"), the file is not meant to be modified and changes will be overwritten. If a file begins with the "soft" generated comment (contains instructions on making changes), then the file will be overwritten as long as that comment is present. If manual changes are made, the comment should be removed to prevent overwriting those changes. The force flag (-f or --force) can be set to force overwriting of all files for any command.

Adding Authentication to an Existing App

To add authentication handling to an existing app, use the authentication command.

Since existing files are not modified by the authentication command, several files have to be updated manually. Required file updates are as follows:

• Contexts/index.ts
  • Export all contents of the AuthenticationContext directory.
  • Note: May not have existed prior to running authentication and would therefore not need to be updated manually.
• index.tsx
  • Add the <AuthenticationManager> as a parent of <App> (must be a child of <PermissionManager>).
• App.tsx
  • Import auth-related pages and setup routing based on authentication status. Tip: delete the App.tsx file temporarily before running authentication to get the suggested format, then merge files manually.
• package.json
  • Add @hex-insights/jwt as a dependency. Can be done with npm i @hex-insights/jwt.

Other Guides

For guides to adding common sets of additional features and functionality, see the Guides document.

For guides on deploying applications, see the Deployment document.

Development

For details on development in this package, see the DEVELOPMENT document.