Skip to content

Get started with NPL

You can start developing NPL in various ways:

  • Use Codespaces to get started without installing anything locally
  • Set up your local NPL development environment locally

Explore these options below by editing, running and deploying to cloud the sample code of a Hello World application.

Please note that if you are trying to do things within a corporate environment you may be restricted from installing (some of) the required 3rd party tools.

Develop in Codespaces

Prerequisite: a GitHub account with Codespaces access.

In the npl-init repository, click on Use this template (visible once logged into your GitHub account) and Open in a codespace at the top right of the screen. This will start a GitHub Codespace, pre-configured with the NPL CLI, the NPL-Dev extension and a sample project.

Once the Codespace is open, you can follow the steps in the README.md.

If you have a NOUMENA Cloud account, your NOUMENA Cloud tenants and applications will be listed in the NOUMENA Cloud pane. Hover over an application and select the upload button to deploy the NPL code. If you have a frontend, you can deploy it as well.

Deploying the Hello World demo frontend from Codespaces to NOUMENA Cloud

In case you want to deploy the complete Hello World demo app, including the frontend, from Codespaces to NOUMENA Cloud, you may repeat the above steps with the npl-demo repository. Before deploying the frontend, adjust webapp/.env, build the frontend and configure users on the NOUMENA Cloud portal as detailed in section Deploy backend and frontend to NOUMENA Cloud below.

For further step-by-step instructions, check out Starter tracks and How-to guides.

Develop locally

Run locally

Prerequisites: these systems need to be installed on your machine

Steps:

  1. Create a new project from the NPL starter template containing the Hello World backend. You can do this by running:

    npl init --project-dir my-project

    However, we recommend to clone and deploy the complete Hello World demo application, including frontend, from the npl-demo repository:

    git clone https://github.com/NoumenaDigital/npl-demo.git

  2. Check the NPL is correct and run the supplied unit tests

     npl check
    npl test

  3. Start the NPL Runtime locally. From the root of the new project, run:

    docker compose up -d --build --wait

  4. Deploy NPL to the NPL Runtime:

    npl deploy

  5. Follow the remainder of the README.md in project directory to interact with the backend deployed locally.

  6. The frontend is built into the demo in development mode and runs in Docker. Navigate to the frontend URL with http://localhost:5173/.

Note that the local deployment uses an embedded OIDC server with seeded users. The embedded OIDC server should be used for development purposes only.

Deploy backend and frontend to NOUMENA Cloud

Prerequisites:

  • The NPL-demo project containing the Hello World application running locally (see above).

  • npm installed or docker we recommend you use docker.

    To clone the NPL-demo repository, run:

    git clone https://github.com/NoumenaDigital/npl-demo.git

Steps:

  1. Sign up to NOUMENA Cloud

  2. Create a new tenant and a new application in the NOUMENA Cloud portal (more details here on application creation, if needed). Pay attention to the resulting tenant and application slugs, as displayed in the portal.noumena.cloud/TENANT_SLUG/APPLICATION_SLUG URL of your application.

  3. Adjust the npl.yml file in your project root folder to match your NOUMENA Cloud tenant and application slugs by setting the cloud.tenant and cloud.app properties accordingly.

  4. Also log in from the command line using the NPL CLI:

    npl cloud login

    This will open a browser window to authenticate with NOUMENA Cloud. Provide your credentials, choose Sign In, and grant access privileges. After successful authentication, you can close the browser window and return to the terminal.

  5. Deploy the NPL source code by running the following command from the npl-demo/ root of the cloned repository:

    npl cloud deploy npl

    If you are deploying once more, clear the NPL package first (or implement a migration):

    npl cloud clear && npl cloud deploy npl

    Note that you can also provide the tenant slug, application slug and path to the migration file directly as command line arguments (--tenant, --app, --migration) to the above commands, overriding the values set in npl.yml. For more information, type npl cloud deploy help.

    With this step, you already have a fully functional backend running on NOUMENA Cloud, as reflected by the Swagger UI available under https://engine-TENANT_SLUG-APPLICATION_SLUG.noumena.cloud. Let's now deploy the frontend to NOUMENA Cloud.

  6. Change the webapp/.env file to match your NOUMENA Cloud tenant and application. Make sure to use the tenant and application slugs rather than the full names

  7. From the project root directory, build the frontend:

    docker compose build webapp

    Alternatively, if you do not have Docker installed, but do have npm installed, from the webapp directory

     npm i && npm run build

  8. From the project root directory, deploy the frontend to NOUMENA Cloud

    npl cloud deploy frontend

    This uses values for the tenant slug, application slug and path to the frontend build that are defined in npl.yml. You can override these settings with command line arguments (--tenant, --app, --frontend). For more information, type npl cloud deploy help.

  9. Configure users on the NOUMENA Cloud portal. You will need to create alice, bob and carol users according to the create application users guide.

    The hardcoded demo password in the webapp is password12345678 for all users. Feel free to change it to your liking, ensuring that the password of application users created on NOUMENA Cloud is matching the one used across the webapp.

  10. Navigate to the https://TENANT_SLUG-APPLICATION_SLUG.noumena.cloud frontend URL of your NOUMENA Cloud application and try out the Hello World application flow

Edit NPL in your IDE

The tools listed above are the minimum required for the following steps, however to work effectively work with NPL you also need to install an IDE which supports NPL, if you don't already have one. We have NPL support for

  • VS Code
    • VS Code (and clones of VS Code like Cursor) are supported with the VS Code extension
    • VS Code is recommended for working with AI
    • [Windows] There is an extension for working inside WSL
  • IntelliJ
    • The plugin works with any of the IntelliJ variants (Community, Ultimate, WebStorm, PyCharm, etc.)
    • IntelliJ is recommended for development work such as debugging and testing
    • IntelliJ bundles additional tools like Maven and Gradle
    • [Windows] IntelliJ will detect the Git executable in WSL, IntelliJ can be configured to use WSL as the shell

Prerequisites:

  • Hello World backend code created with npl init or complete Hello World application (backend and frontend) code cloned from npl-demo repository (see Run locally)

Steps:

  1. Install the embedded NPL-Dev Plugin in your IDE (IntelliJ, VS Code, or VS Code-derived)

  2. Edit the NPL code in the api/src/main directory. You may for example start by changing the string (Text) returned by the sayHello permission

  3. From the npl-demo root of the cloned repository, start the NPL Runtime and the Frontend locally. Make sure the webapp/.env specifies the local host in the Vite environment variables

    git checkout master webapp/.env
docker compose up -d --build --wait

  4. Clear and upload the NPL code to the NPL Runtime

    npl deploy --clear

  5. The frontend is built into the demo in development mode and runs in Docker. Navigate to the frontend URL with http://localhost:5173/. The docker compose set up uses volumes, so changes to FE code are picked up by the Vite Hot Module Replacement and there is no need to restart the server. If you need to restart the server you can do this

    docker compose up -d --build --wait --no-deps --force-recreate webapp

Take your next steps

Now you are familiar with development and deployment options: