# NavSphere keeps a navigation site in three JSON files on GitHub

> NavSphere is a Next.js navigation platform for video collections and bookmarks that stores its data in a GitHub repository, with the admin UI writing JSON through the GitHub API, drag and drop ordering, a Monaco editor for direct data edits, and one click deployment to Cloudflare Pages or Vercel. It suits people who want a bookmark site with no database to maintain.

**tianyaxiang/NavSphere** — NavSphere： 一个基于 Github 存储的网址导航程序支持部署至cloudflare，一键部署至 Vercel，数据存储在 Github，零成本搭建一个网站导航！

- Repository: https://github.com/tianyaxiang/NavSphere
- Website: https://nav.newkit.site
- Stars: 833 · Forks: 628
- Language: TypeScript
- License: MIT
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/tianyaxiang-navsphere

## The database is a repository and a branch

The architecture decision that shapes everything else is that the GitHub repository is the data backend. The README describes NavSphere as a modern navigation management platform built on Next.js 15 that integrates video navigation and website navigation, designed for collecting, categorising and managing content, and it uses GitHub as the storage backend to provide what it calls a secure and reliable navigation data management experience. The practical result is that there is no database server to operate and no hosting cost for one, since the project description says the data is stored on GitHub so you can build a navigation site at zero cost. The runtime reads and writes JSON in a repository and branch you name, using `@octokit/rest` to talk to the GitHub API, and the site itself can be hosted on Cloudflare Pages, Vercel, or a container.

## Two separate collections in one interface

The platform has two cores that share the admin shell. Video navigation is for collecting and organising video content, with support for Bilibili and YouTube, and it recognises those links automatically, extracts the video information, and can play them embedded on the site. Website navigation is a bookmark manager for sites, online tools and resources, with automatic favicon fetching or a manual upload, a description, keyword search, tags, and one click access to the target site. Both sit under the same category system, with main categories and sub categories and unlimited depth, and both can be reordered by dragging. The admin side is unified, so the same add, edit, delete and search screens cover the two, with a fast add path for each: paste a video link for a video, or type a URL and let the site fetch the details for a bookmark.

## Three JSON files with a fixed shape

The data model is visible in the documentation and it is deliberately plain. The project creates three files in the data repository: `videos.json` for video data, `navigation.json` for the bookmark data, and `site.json` for site configuration. Each of the two content files has the same envelope, an object with a `navigationItems` array, and each item in that array is either a category or a link. A category carries an `id`, `title`, `icon`, `description`, an `enabled` flag, an `items` array and a `subCategories` array, and a link carries an `id`, `title`, `href`, `description`, `icon` and `enabled`. A video link adds a `videoConfig` object with the `type`, the `bvid`, the `aid`, the `cid` and the part number `p`. Icons are names from the Lucide set, and images are paths under `/assets/`. Because the format is documented, you can write to it from a script, and the admin interface includes a Monaco Editor for editing the JSON directly when the form is not the right tool.

## GitHub OAuth for admins, a token for anonymous submissions

Authentication has two halves, and the second one is the interesting design decision. Sign in is based on NextAuth.js v5 OAuth against GitHub, configured with a GitHub OAuth App whose callback URL is `http://localhost:3000/api/auth/callback/github` in development. Separately, the environment includes a GitHub fine-grained personal access token, and the comment on it says it is used for anonymous submissions that create an issue. In other words, a visitor who is not logged in can still contribute, and their contribution arrives as an issue in the data repository for the owner to approve, rather than as a direct write. That is a sensible way to run a public site whose data is a git repository, and it is also the part of the setup that deserves the most attention, since a token that can create issues in your repository is a credential with real standing.

## Running it locally with pnpm and an env file

The requirements are Node.js 20.0 or later, pnpm 8.0 or later as the recommended package manager with npm or yarn as alternatives, and a GitHub account. The install is four steps. Clone the project:

```bash
git clone https://github.com/tianyaxiang/NavSphere.git
cd NavSphere
```

Install the dependencies:

```bash
pnpm install
```

Create the local environment file from the template:

```bash
cp .env.example .env.local
```

and then start the development server with `pnpm dev` and open `http://localhost:3000`. The variables you need to fill in are the GitHub OAuth client id and secret, the owner, repository and branch of the data repository, the fine-grained token, the NextAuth URL and secret, the public API URL, and optionally a Google Analytics id. The example values are the obvious placeholders, and the README notes that a data repository named `navsphere-data` is recommended, with public or private both possible.

## Cloudflare Pages, Vercel and Docker are all wired up

The deployment section recommends Cloudflare Pages, and the repository carries the configuration for it, with a `wrangler.toml` at the root and a `cf:deploy` script that runs `wrangler pages deploy .next --project-name navsphere` after a `cf:build`. There is a `vercel.json` for the other path, and a `functions/` directory alongside a `_worker.js` file, which is the Cloudflare Pages Functions shape for handling requests that need more than static output. The Docker route is the third, with `docker:build` using `docker/Dockerfile` and a compose file for development and a separate one for production, plus a `docker:deploy` script that shells out to `scripts/docker-deploy.sh`. The design intent is that the same Next.js application runs in all three, and the GitHub data layer means only the environment variables differ between them.

## A conventional stack with a version story to check

The stack is documented in a table, and it is the sort of list you can read to judge the age of the project. Next.js 15.5.7, React 18.2.0, TypeScript 5.1.6, Tailwind CSS 4.1.12, NextAuth.js at 5.0.0-beta.25, Radix UI, Lucide React 0.462.0, React Query 5.62.2, React Hook Form 7.53.2, Zod 3.25.76 and Monaco Editor 0.52.2, with the interface built on Radix UI and shadcn/ui, drag and drop handled by `@hello-pangea/dnd` and the GitHub API by `@octokit/rest`. The licence is MIT and there are three READMEs, one in Chinese, one in English and one more, alongside a `doc/` and a `docs/` directory. The release history shows v1.0.7 on 2025-12-20, v1.0.8 on 2026-01-27 and v1.0.9 on 2026-04-18, with the last push on 2026-08-22, while the package manifest still carries version `0.1.0`. That mismatch is a small warning sign, and it is the kind of detail worth checking when you decide which commit to deploy.

## Conclusion

Adopt NavSphere when you want a shared bookmark and video collection with no database to run, since the whole data layer is three JSON files in a GitHub repository that the admin UI edits through the API, and the platform deploys to Cloudflare Pages or Vercel from the same code. Do not adopt it when you need high write volume, transactional updates or an audit trail, because every edit becomes a commit and an issue in a repository. Verify first that your GitHub token has the scopes the deployment needs, that the data repository can be public or private as you intend, and that the anonymous submission path with the fine-grained personal access token is acceptable to you, since that token can create issues in the repository.

## FAQ

### Where does NavSphere store its navigation data?

In a GitHub repository you name, as three JSON files, `videos.json`, `navigation.json` and `site.json`. The application reads and writes them through the GitHub API using `@octokit/rest`, so there is no separate database to run.

### How do I run NavSphere locally?

You need Node.js 20.0 or later and pnpm 8.0 or later. Clone the repository, run `pnpm install`, copy `.env.example` to `.env.local` and fill in the GitHub OAuth, repository, token and NextAuth values, then run `pnpm dev` and open http://localhost:3000.

### What is the GitHub personal access token used for?

The environment file documents it as a GitHub fine-grained personal access token used for anonymous submissions that create an issue, so a visitor who is not logged in can still submit content for the owner to review.

### Can NavSphere be deployed to Cloudflare Pages and Vercel?

Yes. The repository ships a `wrangler.toml` and a `cf:deploy` script that runs `wrangler pages deploy .next --project-name navsphere`, a `vercel.json` for Vercel, and Docker scripts for a container deployment, so the same application runs on all three with only the environment variables changing.

## Sources

- [License: MIT](https://github.com/tianyaxiang/NavSphere/blob/main/LICENSE)
- [Project website](https://nav.newkit.site)
- [README](https://github.com/tianyaxiang/NavSphere/blob/main/README.md)
- [Releases](https://github.com/tianyaxiang/NavSphere/releases)
- [tianyaxiang/NavSphere on GitHub](https://github.com/tianyaxiang/NavSphere)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/tianyaxiang-navsphere