Installation | Grafos

Install Grafos into a new or existing Next.js project and verify everything works.

Grafos is a library that you add to a Next.js project. This guide covers the requirements, installation steps, initial configuration, and verification.

Requirements

Before installing Grafos, make sure your environment meets the following requirements:

Next.js 16+ with the App Router enabled. Grafos uses App Router conventions for layouts, pages, and API routes.
pnpm as your package manager. Grafos is tested with pnpm and the CLI scaffolds pnpm-based projects.
Tailwind CSS v4 for styling. Grafos provides a Tailwind preset that requires v4's CSS-first configuration.

Node Version

Grafos requires Node.js 24 or later. You can check your version with:

node --version

If you need to upgrade, we recommend using a version manager like fnm or nvm:

fnm install 24
fnm use 24

Install Package

Add Grafos to your project:

pnpm add grafos

This installs the core framework package which includes:

The defineConfig() function for type-safe configuration
React components for the graph, search, sidebar, and other UI elements
The unified markdown pipeline (remark + rehype) with all transforms
The Tailwind CSS v4 preset
The pre-build CLI that generates cache artifacts

If you are starting from scratch, consider using the quick-start CLI instead, which scaffolds a complete project for you.

You will also need the peer dependencies that Grafos expects in your project:

pnpm add next react react-dom tailwindcss

If you already have a Next.js project, these are likely already installed. Grafos declares them as peer dependencies so it does not force specific versions on you.

Configuration

Create a grafos.config.ts file in your project root:

import { defineConfig } from 'grafos'

export default defineConfig({
  site: {
    title: 'My Wiki',
    description: 'A personal knowledge base',
    baseUrl: 'https://wiki.example.com',
  },
  content: {
    directory: 'content',
  },
  features: {
    graph: true,
    search: true,
    backlinks: true,
    toc: true,
  },
})

The defineConfig() function provides full TypeScript autocompletion and validation for every option. See configuration for the complete reference.

Create the content directory:

mkdir content

Add a first page at content/index.md:

---
title: Home
description: Welcome to my wiki
tags: [home]
---

# Welcome

This is your first Grafos page.

See content-directory for details on how Grafos discovers and processes markdown files.

Verify Installation

Start the development server:

pnpm dev

If everything is configured correctly, you should see:

Your site running at http://localhost:3000
The home page rendering with your markdown content
No errors in the terminal related to Grafos

You can also verify that the pre-build step ran by checking for the .grafos/ directory in your project root. It should contain:

manifest.json — metadata for all pages
graph.json — nodes and edges for the 3D graph
search-index.json — full-text search index
file-tree.json — folder hierarchy for the sidebar

If the .grafos/ directory does not exist after starting the dev server, the pre-build step may not be configured. Make sure grafos is listed in your dependencies and that your dev script triggers the Grafos build step before Next.js starts.

If you run into issues, check the following:

Node.js version is 24 or later
grafos.config.ts exists in the project root
The content/ directory exists and contains at least one .md file
Tailwind CSS v4 is installed and configured

Once your installation is verified, proceed to quick-start to learn about the CLI and content authoring workflow, or jump to configuration to explore all available options.