Endpoints

While Nokkio provides much of the functionality you would usually write backend code for, there are scenarios where you may need to perform operations on the server that are not feasible or secure to perform in a browser.

Nokkio Endpoints are backend functions that share the familiar, file-based routing that your Nokkio pages use and are deployed along with the rest of your application. Endpoints are securely run on nokk.io infrastructure.

Your first endpoint

Endpoints are defined in server/endpoints and adhere to a contract built around the Fetch web APIs:

function handler(request: Request): Promise<Response>;

To create an endpoint that echoes out a simple response, create a file at server/endpoints/hello-world.js.

export default async function() {
  return new Response('Hello!');
}

To test the endpoint, start your project with nokkio dev, then load http://localhost:9000/_/endpoints/hello-world in a browser.

For more detail on writing endpoints, see the writing endpoints guide.

The endpoints runtime

Nokkio endpoints run on Deno, a Javascript runtime that resembles the web and uses many of the browser APIs you are already familiar with. Because of this, there are a few things to watch out for when writing endpoints, particularly if you are used to writing Node.js.

Local imports

When importing other modules in your endpoints, you must include the file extension when referencing the module's path. For example:

// This would not work:
// import { add } from '../utils/math';
import { add } from '../utils/math.js';

export default async function () {
  const result = add(2, 2);
  return new Response('2 + 2 is ' + result);
}

External dependencies

When using Deno, you do not install external dependencies via the command line. Importing the external dependency in your endpoint logic will automatically fetch that dependency.

To accomplish this, Deno supports full URLs as import paths when using external dependencies:

import { sum } from 'https://deno.land/x/math@v1.1.0/mod.ts';

export default async function () {
  const result = sum([2, 2]);
  return new Response('2 + 2 is ' + result);
}

When Nokkio builds your endpoints, it will automatically fetch any remote dependencies.

Using npm packages

Deno also supports most npm packages by prefixing the import path with npm:.

import { format } from 'npm:date-fns@^2.29';

export default async function () {
  return new Response(
    format(new Date(), "'Today is a' eeee")
  );
}

For more on using npm specifiers, see the Deno documentation.

Using Node.js built-in modules

Deno also supports most Node.js built-in modules by prefixing the import path with node:.

import { json } from '@nokkio/endpoints';
import { createHash } from 'node:crypto';

export async function post(req) {
  const { email } = await req.json();

  const hash = createHash('md5')
    .update(email.toLowerCase())
    .digest('hex');

  return json({
    email_hash: hash,
  });
}

For more on using npm specifiers, see the Deno documentation.