Around 1.5 months ago, I took on two projects that uses Next.js and Supabase. I was initially very excited to have real projects to work on, with the guidance of seasoned professionals.
But after working on each project for around 5-10 hours, I stalled. There just seemed to be so many nitty-gritty little things I had to learn in an unpleasant stop-and-start fashion. For example,
Next.js clearly uses the directory structure to mirror different URL routes. But then why do some tutorials use a “app” directory and others a “pages” directory at the root of the project?
some directory names (e.g. “api”) and some file names (“pages” and “layout”) clearly have special meanings. But which? And why is it sometimes I have to add “use client” to make things work?
Soon, little frustrations added up; working on the projects was not fun any more and I left then by the wayside.
But after a while, I realised the obvious: I had come into the whole thing with only really rudimentary knowledge of Next.js from doing the guided quick start tutorial.
Perhaps getting my hands dirty, I really should read the docs (for 2-3 hours) first.
This proved to be quite an enjoyable exercise. The Next.js docs are very well-written. The pace is fast, and there are good places where you can skip/skim without compromising understanding. At the very least, it helped me answer my questions above:
At the root directory level, “Pages” v. “App” directories belong to two different generations of Next.js. To ensure backwards compatibility, “Pages” is still supported: which explains why some old tutorials still “work”.
The docs clearly explains the special names available for files and directories. I am especially impressed by the fact that some directories and files are specifically designed not to be exposed to the user as routes: the term used in the docs is “Not Routable”.