A Harper Extension for running and developing Next.js apps.
Most Next.js features are supported as we rely on the Next.js Server provided by Next.js to run your application.
Tip
Watch a walkthrough of this component in action here: Next.js on HarperDB | Step-by-Step Guide for Next Level Next.js Performance
Note
This guide assumes you're already familiar with Harper Components. Please review the documentation, or check out the Harper Next.js Example for more information.
- Install:
npm install @harperdb/nextjs- Add to
config.yaml:
'@harperdb/nextjs':
package: '@harperdb/nextjs'
files: '/*'- Run your app with
harperdb:
harperdb run nextjs-appAlternatively, you can use the included harperdb-nextjs CLI:
harperdb-nextjs build | dev | start- Within any server side code paths, you can use Harper Globals after importing the
harperdbpackage:
// app/actions.js
'use server';
import('harperdb');
export async function listDogs() {
const dogs = [];
for await (const dog of tables.Dog.search()) {
dogs.push({ id: dog.id, name: dog.name });
}
return dogs;
}
export async function getDog(id) {
return tables.Dog.get(id);
}// app/dogs/[id]/page.jsx
import { getDog, listDogs } from '@/app/actions';
export async function generateStaticParams() {
const dogs = await listDogs();
return dogs;
}
export default async function Dog({ params }) {
const dog = await getDog(params.id);
return (
<section>
<h1>{dog.name}</h1>
<p>Breed: {dog.get('breed')}</p>
<p>Woof!</p>
</section>
);
}Harper relies on native dependencies and must be configured as an external package. In Next.js v14, update the next.config.js webpack option with:
webpack: (config) => {
config.externals.push({
harperdb: 'commonjs harperdb',
});
return config;
},All configuration options are optional
Specify a custom build command. Defaults to next build.
Note: the extension will skip building if the
prebuiltoption is set totrue
Build the Next.js application and then exit (including shutting down HarperDB). Defaults to false.
Enables Next.js dev mode. Defaults to false.
Specify a port for the Next.js server. Defaults to the Harper default port (generally 9926).
When enabled, the extension will look for a .next directory in the root of the component and skip executing the buildCommand. Defaults to false.
Configure the Next.js request handler to run first in the Harper HTTP middleware. When enabled, the Next.js request handler is executed before any other Harper HTTP middleware handlers. This is useful for things such as handling authentication directly with the Next.js app instead of delegating that to Harper. Enabling this option will conflict with other Harper HTTP things such as the REST API. Consider specifying the port (or securePort) option as well and separating the Next.js app HTTP server from the rest of Harper so there is less conflicts. Defaults to false.
Specify a secure port for the Next.js server. Defaults to the HarperDB default secure port.
Harper will set the current working directory to the root of the Next.js app. Necessary for some Next.js and React libraries. Can cause other issues with Harper Components. Use with caution. Defaults to false.
This package includes a CLI (harperdb-nextjs) that is meant to replace certain functions of the Next.js CLI. It will launch Harper and set sensible configuration values.
Available commands include:
Launches the application in Next.js development mode, and enables HMR for instantaneous updates when modifying application code.
Note
Dev mode for Next.js v13+ relies on WebSockets. If you encounter an Invalid WebSocket frame: error, disable any other WebSocket services on the Next.js port. This commonly can be the HarperDB MQTT WebSocket service, which can be configured under the mqtt option within harperdb-config.yaml.
Builds the application and then exits the process.
Launches the application in Next.js production mode.
Lists available CLI commands.