Getting Started

After installing the Nitric CLI, you can start building a project.

Using the new command

The Nitric CLI's new command provides prompts to scaffold new projects from templates. In this example we'll select the TypeScript starter template. The CLI also needs to know which source files represent your application code. In this example all of our app code is inside the functions/ folder, so we provide a glob pattern to match that folder.

nitric new
? What is the name of the stack? hello-world
? Choose a template: official/TypeScript - Starter
? Glob for the function handlers? functions/*.ts

Navigate to the new project directory and install the NPM dependencies:

cd hello-world
npm install

Your project should now look like this:

+--functions/
| +-- hello.ts
+--node_modules/
| ...
+--package-lock.json
+--package.json
+--README.md

Running your app

The Nitric CLI can run your application locally for development and testing.

nitric run

Output:

SUCCESS Configuration gathered (2s)
SUCCESS Created Dev Image! (0s)
SUCCESS Started Local Services! (2s)
SUCCESS Started Functions! (0s)
Local running, use ctrl-C to stop
Api | Endpoint
main | http://localhost:9001/apis/main

Take a look in the hello.ts file, you'll see it declares an API named main with a single route GET /hello/:name.

When running locally Nitric hosts all your APIs under the path:

http://localhost:9001/apis/[api_name]/

in this case the URL for the API is:

http://localhost:9001/apis/main/

You can test the API using cURL, your browser, or any other HTTP client:

curl http://localhost:9001/apis/main/hello/John
Hello John

Making updates

The run command supports hot reload by default, so let's make some changes and see what happens.

Open functions/hello.ts in your editor and add a new route to the API, then save the file:

import { api } from '@nitric/sdk';
const helloApi = api('main');
helloApi.get('/hello/:name', async (ctx) => {
const { name } = ctx.req.params;
ctx.res.body = `Hello ${name}`;
return ctx;
});
// add this
helloApi.get('/goodbye/:name', async (ctx) => {
const { name } = ctx.req.params;
ctx.res.body = `Goodbye ${name}`;
return ctx;
});

After saving, the new route will be registered and you can test it:

curl http://localhost:9001/apis/main/goodbye/John
Goodbye John

When you're finished running press ctrl + c to stop the run command.

Deploying the app

Now that you've implemented a basic API and tested that it works, you can deploy it to one of the major cloud platforms.

The first step is to set up your credentials for the cloud provider.

You'll then need to create a stack which represents your project and a deployment target.

nitric stack new

Follow the prompts to create a stack for your provider, this example will use aws.

? What do you want to call your new stack? dev
? Which Cloud do you wish to deploy to? aws
? select the region us-east-1

Now you can deploy your stack named dev with the up command.

nitric up -s dev

Output:

SUCCESS Configuration gathered (2s)
SUCCESS Images built (3s)
Deployed Function/hello (15)
Deployed Stack (25s)
┌───────────────────────────────────────────────────────────────┐
| API | Endpoint |
| main | https://XXXXXXXX.execute-api.us-east-1.amazonaws.com |
└───────────────────────────────────────────────────────────────┘

When the deployment is complete, go to the relevant cloud console and you'll be able to see and interact with your API.

To undeploy this stack -

nitric down -s dev

What's next?