https://github.com/harperdb/nextjs
A HarperDB Component for running and developing Next.js apps.
https://github.com/harperdb/nextjs
harperdb nextjs react ssr webapplication
Last synced: 10 months ago
JSON representation
A HarperDB Component for running and developing Next.js apps.
- Host: GitHub
- URL: https://github.com/harperdb/nextjs
- Owner: HarperDB
- License: mit
- Created: 2024-08-13T22:24:38.000Z (over 1 year ago)
- Default Branch: main
- Last Pushed: 2025-03-12T18:44:41.000Z (11 months ago)
- Last Synced: 2025-04-12T03:12:29.309Z (10 months ago)
- Topics: harperdb, nextjs, react, ssr, webapplication
- Language: JavaScript
- Homepage: https://www.npmjs.com/package/@harperdb/nextjs
- Size: 282 KB
- Stars: 4
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# @harperdb/nextjs
A [HarperDB Component](https://docs.harperdb.io/docs/developers/components) 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](https://youtu.be/GqLEwteFJYY)
## Usage
> [!NOTE]
> This guide assumes you're already familiar with [HarperDb Components](https://docs.harperdb.io/docs/developers/components). Please review the documentation, or check out the HarperDB [Next.js Example](https://github.com/HarperDB/nextjs-example) for more information.
1. Install:
```sh
npm install @harperdb/nextjs
```
2. Add to `config.yaml`:
```yaml
'@harperdb/nextjs':
package: '@harperdb/nextjs'
files: '/*'
```
3. Run your app with HarperDB:
```sh
harperdb run nextjs-app
```
Alternatively, you can use the included `harperdb-nextjs` CLI:
```sh
harperdb-nextjs build | dev | start
```
4. Within any server side code paths, you can use [HarperDB Globals](https://docs.harperdb.io/docs/technical-details/reference/globals) after importing the HarperDB package:
```js
// 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);
}
```
```js
// 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 (
{dog.name}
Breed: {dog.get('breed')}
Woof!
);
}
```
HarperDB relies on native dependencies and must be configured as an external package. In Next.js v14, update the next.config.js `webpack` option with:
```js
webpack: (config) => {
config.externals.push({
harperdb: 'commonjs harperdb',
});
return config;
},
```
## Options
> All configuration options are optional
### `buildCommand: string`
Specify a custom build command. Defaults to `next build`.
> Note: the extension will skip building if the `prebuilt` option is set to `true`
### `buildOnly: boolean`
Build the Next.js application and then exit (including shutting down HarperDB). Defaults to `false`.
### `dev: boolean`
Enables Next.js dev mode. Defaults to `false`.
### `port: number`
Specify a port for the Next.js server. Defaults to the HarperDB default port (generally `9926`).
### `prebuilt: boolean`
When enabled, the extension will look for a `.next` directory in the root of the component and skip executing the `buildCommand`. Defaults to `false`.
### `securePort: number`
Specify a secure port for the Next.js server. Defaults to the HarperDB default secure port.
### `setCwd: boolean`
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`.
## CLI
This package includes a CLI (`harperdb-nextjs`) that is meant to replace certain functions of the Next.js CLI. It will launch HarperDB and set sensible configuration values.
Available commands include:
### `dev`
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`.
### `build`
Builds the application and then exits the process.
### `start`
Launches the application in Next.js production mode.
### `help`
Lists available CLI commands.