Zum Hauptinhalt springen

Create a Jutro app

You can use our starter application to get started. This application gives you all the source code with examples.

Prerequisites​

  • Node version: >=22.6.0 < 23
  • npm: >=10.8.2

Follow installation instructions depending on your operating system.

Get access to Artifactory​

To get started with Jutro, set up your connection to the Jutro NPM repository in Artifactory.

If you do not have access to artifactory, you can request it in ServiceNow.

Repositories​

jutro-suite-npm-dev repository is configured as proxy for a set of repositories where different JDP artifacts are stored but also for the public NPM registry. This allows developers to have a simplified set up by only configuring the access to this repository (instructions are listed below), and it is the recommended approach.

However, it is important to highlight that:

  1. The NPM install performance using this repository as proxy might be worse than using the proxied repositories directly
  2. In case of configuring the proxied repositories access individually, configure the NPM scopes also

The main repository for JDP artifacts is jutro-npm-dev-local and it contains the following scopes:

  • @jutro
  • @digitalsdk
  • @jutro-experimental
Note: In case you are a Guidewire developer working on the Guidewire team you should use the dedicated internal repository. Check the internal documentation to understand the difference between external and internal repositories.

Set up your machine to use NPM packages from Artifactory​

NPM packages required for Jutro apps are not available in the public NPM registry. Set your .npmrc to look for them in Guidewire Artifactory.

  1. From your Okta homepage, log in to Artifactory.

  2. Run the following command to set up access to the Jutro repository:

    npm config set registry https://artifactory.guidewire.com/artifactory/api/npm/jutro-suite-npm-dev/
    npm login --registry https://artifactory.guidewire.com/artifactory/api/npm/jutro-suite-npm-dev/
    npm config set legacy-peer-deps true

  3. Follow the prompt in the terminal and press Enter to open a new browser window. You should now be successfully logged in.

Note: In case of configuring the access to individual repositories, use the instructions from Set up your local environment but using the corresponding URL and repository: (https://artifactory.guidewire.com/artifactory/api/npm/jutro-npm-dev-local)

Initiate a new Jutro app​

We recommend using Node 22 when bootstrapping a new app. You can get the starter app from Artifactory using the npx command.

  1. In the directory where you want to create a sub-directory with the Jutro app, run the following command:
npx @jutro/create-app@<version> <app-name>

For "version", you can use one of the following:

  • latest - The latest, official, published version (eg, "2.0.5")
  • next - The most recent, development build from the main branch (eg, "2.0.5-next.12345")
  • specific version, for example 3.4.0

<app-name> is referenced in the application code and also becomes the folder for your application. Follow prompts to configure your application.

For example, if you run the following command, you create a frontend folder that contains all your application files:

# Before you do anything,
# Make sure you're using the correct version of Node.js!
# See the prerequisites above

# You can enter a specific version of Jutro
npx @jutro/create-app@7.5.0 frontend

# Use "latest" to automatically get the highest published version of Jutro
npx @jutro/create-app@latest frontend
Warning: Invalid project name

If you get an error like:

Invalid project name. Only alphanumeric and

- _ @ . / \

characters allowed!

make sure your folder name does not contain any spaces or other forbidden characters.

  • ✅ right: galaxy-frontend
  • ❌ wrong: My new project (3)

During the installation, you may decide to include husky in your project. If you answer "yes" to one of the following questions:

  • "Enable ESLint, Prettier, and stylelint commit hooks?" or
  • "Enable commit message linting hook?" remember that husky won't work right away because Jutro app is installed without Git initialized.

To fix it, run

git init
npm install

You will already have a postinstall script inside your package.json that will always install husky after npm install command.

Run the starter application in interactive mode​

npm start

Next steps​

See the Quickstart for developers page for a brief overview of developing with Jutro, or follow the Learning Missions for a more guided tutorial on specific features of Jutro.

Troubleshooting​

Error installing Playwright​

Wenn Sie mit ZScaler verbunden sind und versuchen, npm install auszuführen, versucht der Befehl, das Modul playwright in Abhängigkeit von @jutro/e2e-tests zu installieren und schlägt fehl.

Dies ist ein Zertifikatsproblem und Sie können eines der folgenden Workarounds verwenden:

  • (Empfohlen) Laden Sie das benutzerdefinierte CA-Zertifikat herunter, das von den Guidewire-Netzwerkadministratoren bereitgestellt wird, und stellen Sie es npm auf eine der folgenden Arten zur Verfügung:

    • Verwenden Sie die env-Variable:

      Für MacOS:

      echo "export NODE_EXTRA_CA_CERTS=<Path to Certificate>\ZscalerRootCertificate-2048-SHA256.crt" >> $HOME/.bashrc
      Note: Stellen Sie sicher, dass Sie die passende Konfigurationsdatei für Ihre Shell verwenden, z. B. ersetzen Sie .bashrc durch .zshrc, wenn Sie die zsh-Shell verwenden.

      Für Windows:

      [System.Environment]::SetEnvironmentVariable("NODE_EXTRA_CA_CERTS", "C:<Path to Certificate>\ZscalerRootCertificate-2048-SHA256.crt", "Machine")

      Sie können die MacOS-Lösung auch in einer Windows-Umgebung anwenden, indem Sie sie in der Git Bash-Shell anwenden.

      Darüber hinaus ermöglicht die Verwendung der Exportvariablen die Verwendung aller vorhandenen CA-Zertifikate. Dies gilt ebenso wie die ZScaler-Versionen.

  • Deaktivieren Sie vorübergehend den Abschnitt „Internet Security“ in Zscaler für die Zeit der Installation von Abhängigkeiten (npm install / yarn install) im Projekt:

Zscaler mit deaktivierter Internetsicherheit

VPN error​

When using VPN, you may get the following error:

npm ERR! Error: UNABLE_TO_VERIFY_LEAF_SIGNATURE

Solution: Run the following command:

npm config set strict-ssl false

Dev server returns index.html for any request​

You may encounter an issue that looks like the following:

Console showing Uncaught SyntaxErrors

This occurs when the homepage property in your application's package.json file is set to the . character (period, also known as full stop).

Solution: Remove the homepage field, or set its value to an empty string.

Maximum call stack exceeded with module federation​

You may encounter a "Maximum call stack size exceeded" error that looks like the following:

Uncaught (in promise) RangeError: Maximum call stack size exceeded
  at <anonymous>: 2:23963
  at Array. forEach (<anonymous>)
  at Object. t.f. consumes (anonymous>: 2:23753)
  at anonymous>: 2:2204
  at Array. reduce (<anonymous>)
  at Function.t.e (<anonymous>:2:2169)
  at Object. get (<anonymous>: 2:14179)
  at a (<anonymous>: 2:16873)
  at f (<anonymous>: 2:16707)
  at <anonymous>:2:17046

This is caused by webpack having issues compiling the history package as a shared dependency.

Solution: Remove the history package from the list of shared packages.

Incompatible ARM binaries​

When running npm commands on a Mac computer with a M1 chip, you may encounter an error whose details say there is an 'incompatible architecture (have (x86_64), need (arm64e))'.

Execute the following steps to solve this issue:

  1. Install node version manager (nvm) if you do not already have it installed.
  2. Check your node version by running the node -v command in your terminal.
  3. Check your node architecture by running the node -p process.arch command in your terminal. This should print arm64.
  4. If you are using zsh, run the arch -x86_64 zsh command in the same terminal. If you close the terminal then arch will revert to arm64.
  5. Uninstall your current node version using the nvm uninstall command, and then install version 22.6.0 by running the nvm install v22.6.0 command.
  6. Remove the node_modules directory from your project.
  7. Run npm install.

Cannot find module '../build/Release/canvas.node'​

If your canvas module version is not at least 2.11.2, you may encounter the error Cannot find module '../build/Release/canvas.node'.

Solution: Add the following entries to the resolutions section in package.json:

  • "resemblejs": "5.0.0"
  • "canvas": "^2.11.2"

Run npm rebuild to complete this fix.