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 - all you need is the NPL CLI, docker, and NPL IDE plugins.
Explore these options below by editing, running and deploying to cloud the sample code of a Hello World
application.
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 codespaces
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: docker
and (optionally) npm
installed. We recommend Windows Subsystem for Linux (WSL) when using
Windows.
Steps:
-
Get the CLI (MacOS/Linux/Windows with WSL):
brew install NoumenaDigital/tools/npl
curl -s https://documentation.noumenadigital.com/get-npl-cli.sh | bash
You may have to restart the terminal to ensure the CLI is available in your PATH after installing the NPL CLI.
Download and install the latest
.exe
executable here. -
Create a new project from the NPL starter template containing the
Hello World
backend. You can do this by running:npl init --projectDir my-project
Alternatively, if you want to deploy the complete
Hello World
demo application, including frontend, you can clone the npl-demo repository:git clone https://github.com/NoumenaDigital/npl-demo.git
-
Start the NPL Runtime locally. From the root of the new project, run:
docker compose up -d
-
Deploy NPL to the NPL Runtime:
npl deploy --sourceDir api/src/main/
-
Follow the remainder of the README.md in project directory to interact with the backend deployed locally.
-
If you have cloned
npl-demo
and want to run the frontend locally, execute the following from thewebapp
directory:npm i && npm run dev
Navigate to the frontend URL 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:
-
npm
installed -
NPL CLI
installed (see above) -
The NPL-demo project containing the
Hello World
application running locally.To clone the NPL-demo repository, run:
git clone https://github.com/NoumenaDigital/npl-demo.git
Steps:
-
Sign up to NOUMENA Cloud
-
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>/<app-slug>
URL of your application. -
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.
-
Deploy the NPL source code by running the following command from the
npl-demo/
root of the cloned repository and replacing$YOUR_TENANT_SLUG
and$YOUR_APP_SLUG
with the slugs you noted in the previous step:npl cloud deploy npl --tenant $YOUR_TENANT_SLUG --app $YOUR_APP_SLUG --sourceDir api
If you are deploying once more, clear the NPL package first (or implement a migration):
npl cloud clear --tenant $YOUR_TENANT_SLUG --app $YOUR_APP_SLUG && \ npl cloud deploy npl --tenant $YOUR_TENANT_SLUG --app $YOUR_APP_SLUG --sourceDir api
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>-<app-slug>.noumena.cloud
. Let's now deploy the frontend to NOUMENA Cloud. -
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 -
From the webapp directory, build the frontend:
npm i && npm run build
-
Deploy the frontend to NOUMENA Cloud
npl cloud deploy frontend --tenant $YOUR_TENANT_SLUG --app $YOUR_APP_SLUG --sourceDir dist
-
Configure users on the NOUMENA Cloud portal. You will need to create
alice
,bob
andcarol
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. -
Navigate to the
https://<tenant-slug>-<app-slug>.noumena.cloud
frontend URL of your NOUMENA Cloud application and try out the Hello World application flow
Edit NPL in your IDE
Prerequisites:
-
docker
and (optionally)npm
installed -
NPL CLI
installed (see Run locally) -
Hello World backend code created with
npl init
or complete Hello World application (backend and frontend) code cloned fromnpl-demo
repository (see Run locally)
Steps:
-
Install the embedded NPL-Dev Plugin in your IDE (IntelliJ, VS Code, or VS Code-derived)
-
Edit the NPL code in the
api/src/main
directory. You may for example start by changing the string (Text
) returned by thesayHello
permission -
From the
npl-demo
root of the cloned repository, start the NPL Runtime locallydocker compose up -d
-
Clear and upload the NPL code to the NPL Runtime
npl deploy --sourceDir api/src/main/ --clear
-
If using the
Hello World
frontend cloned from thenpl-demo
repository, update the frontend code in thewebapp
directory (in particular revert to local URLs inwebapp/.env
if you have deployed to NOUMENA Cloud previously) and, from thewebapp
directory, install dependencies and run the frontend:npm i && npm run dev
Take your next steps
Now you are familiar with development and deployment options:
- Follow Starter tracks to take your next steps
- Explore more NPL examples
- Check out the reference documentation for the NPL Language, the NPL Runtime and NOUMENA Cloud