New documentation

[franky47]

The playground started as a shell for e2e testing, but evolved into disorganised demos and showcases of what can be done with the library.

Also, the README is starting to become big and hard to digest, so a documentation overhaul would be welcome.

The objective is to keep a single deployable web app that does the following:

• Landing page with overview of features, and a simple demo to showcase sharing.
• Tutorial / Getting started with demos on replacing existing useState
• Recipes / how-to with concrete examples
• Internal pages dedicated to e2e testing, that can be unreachable (no need to link to them). Ideally, they should not be deployed on Vercel and only be used in CI. -> The e2e test bench has been separated in Split e2e and playground #390, and will be kept lean to build quickly in CI.
• Serve as an URL for errors with additional context and remediation, to keep the bundle size small.

Maybe an API reference could be useful (currently covered by the README), especially an exhaustive list of parsers.

Requirements & Specifications

• Be based on Next.js, to showcase the library (rules out Docusaurus)
• Work with the app router (rules out Nextra)
• Support local MDX files for content writing (allows co-location with embedded "use client" demos)
• Search with a simple integration story (Possible solutions: cmdk, minisearch, Algolia DocSearch)
• Syntax highlighting with Shiki
• Styling with TailwindCSS + shadcn/ui for interactive components

Inspirations:

• https://diataxis.fr/
• https://github.com/t3-oss/t3-env/tree/main/docs/
• https://vitepress.dev
• https://github.com/fuma-nama/next-docs

Documentation structure

Installation

• Package manager instructions (npm, yarn, pnpm, bun)
• What version should I use (interactive?)
• Pinning versions (NUQS-409)

Basic usage

• Replacing React.useState
• Default parser is a string
• URL to value mapping (nulls)

Going further

• Parsers
• Options
• Testing
• Server cache

Advanced usage

• Debugging
• SEO
• Throttling server updates
• Batching & awaiting URL updates
• Making your own parsers (w/ lossy caveat)

Recipes (playground)

• Pagination
• Search
• Table filters & sorting options
• Sliders to control UI (colors?)

Reference

• useQueryState
• useQueryStates
• Parsers
• createSearchParamsCache
• subscribeToQueryUpdates (this may be deprecated with WHS)

[Talent30]

Hi, @franky47. How can I help?

[franky47]

@Talent30 I gave next-docs another try today and everything ran fine, even importing client and server components in MDX, so we should be good for embedded interactive demos.

Sandboxes will still make sense as a starting point for users to play with, by not requiring to clone/bootstrap the docs website.

I'll have to give Sandpack a try, but I'm wary of a sandbox trying to emulate browser APIs (history) and how a sandboxed Next.js might work around that, especially for server-oriented features (non-shallow updates, server cache).

[Talent30]

I have tried sandpack. Sadly it doesn’t work with newer version of nextjs. Their template is still running next12.

[Talent30]

stackblitz is working with the latest nextjs now. vercel/next.js@bb25edf
https://stackblitz.com/edit/stackblitz-starters-cyeg8a?file=README.md

[franky47]

CodeSandbox is kind of unreliable regarding Next.js routing:

#430 (comment)

[franky47]

stackblitz is working with the latest nextjs now. vercel/next.js@bb25edf
https://stackblitz.com/edit/stackblitz-starters-cyeg8a?file=README.md

I just tried it and it doesn't update the query string in the browser-in-browser URL, but it does if you open the preview in a new tab.

[franky47]

Added PR #433 with a next-docs app containing a copy of the README as an example.

Looks great out of the box, though images don't seem to be supported due to the Next.js <Image> component requiring image dimension props. I have managed to fix that on my personal website though, so probably can backport there.

[Talent30]

Have you decided which way are you going to use for the interactive demo?

[franky47]

Not yet, CodeSandbox is unreliable, and StackBlitz doesn't show the query in their preview browser-in-browser UI.

I'm looking at GitHub Codespaces too, though that would be more beneficial for issue reproduction.

The plan for the docs PR is to merge the playground and docs apps into a single app, then merge onto next to allow content contributions.

[franky47]

Docs have been merged and are now deployed at nuqs.47ng.com.

There's still some work on:

• Splitting the readme into sections and pages (according to the outline above)
• Presentation on the landing page ("used by" section, footer)
• Fixing the playground pages styles (the tailwind CSS reset broke default browser styles)
• Renaming next-usequerystate into nuqs everywhere relevant