Update docs

Author: kachkaev

.env

@@ -0,0 +1,8 @@
+FLICKR_USER_ID=
+FLICKR_API_KEY=
+
+BASE_URL_EN=
+BASE_URL_RU=
+
+UPDATE_PROFILE_SECURITY_TOKEN=
+UPDATE_PROFILE_PROXY_SERVER_URL=

README.md

@@ -2,55 +2,142 @@
 
 This repository contains the source code of my personal mini-website.
 It represents a simple instance of a Next.js app with server components, API routes and domain-based internationalization.
-Feel free to use this codebase to learn something new or to reuse some of its bits in your own projects.
+Feel free to use this codebase to learn something new or to reuse various bits in your own projects.
 
 ## Key ingredients
 
-- [Next.js](https://nextjs.org) (with `/app` directory) as the architecture framework
-- [React](https://reactjs.org) to define the UI (server and client components)
-- [Tailwind CSS](https://tailwindcss.com) to style the UI
-- [FormatJS](https://formatjs.io) to handle internationalization ([ICU](https://formatjs.io/docs/core-concepts/icu-syntax/) plurals etc.)
-- [Playwright](https://playwright.dev), [Zod](https://zod.dev) and [Axios](https://axios-http.com) to update profile infos in API handlers
-- [ESLint](https://eslint.org), [Markdownlint](https://github.com/DavidAnson/markdownlint), [Prettier](https://prettier.io) and [TypeScript](https://www.typescriptlang.org) to statically check and autocorrect source files
-- [pnpm](https://pnpm.io) to manage dependencies
-- [Docker](https://www.docker.com) to generate deployable production artifacts
-- [Kubernetes](https://kubernetes.io) to run the app in production
-- [GitHub Actions](https://github.com/features/actions) to run CI/CD pipelines
+- **[Next.js](https://nextjs.org)** (with `/app` directory) as the architecture framework
+- **[React](https://reactjs.org)** to define the UI (server and client components)
+- **[Tailwind CSS](https://tailwindcss.com)** to style the UI (including dark/light themes)
+- **[FormatJS](https://formatjs.io)** to handle internationalization ([ICU](https://formatjs.io/docs/core-concepts/icu-syntax/) plurals etc.)
+- **[Google Analytics](https://analytics.google.com)** to track website usage
+- **[Axios](https://axios-http.com)**, **[Zod](https://zod.dev)** and **[Playwright](https://playwright.dev)** to update profile infos in API handlers
+- **[ESLint](https://eslint.org)**, **[Markdownlint](https://github.com/DavidAnson/markdownlint)**, **[Prettier](https://prettier.io)** and **[TypeScript](https://www.typescriptlang.org)** to statically check and autocorrect source files
+- **[pnpm](https://pnpm.io)** to manage dependencies
+- **[Docker](https://www.docker.com)** to generate a deployable production artifact
+- **[Kubernetes](https://kubernetes.io)** to run the app in production
+- **[GitHub Actions](https://github.com/features/actions)** to run [CI/CD](https://en.wikipedia.org/wiki/CI/CD) pipelines
 
-## Short-term plans
+## Project structure
 
-- [ ] finish README
-- [ ] improve locale animation (use framer-motion)
+The codebase is inspired by these Next.js examples:
 
-## Project structure
+- [app-dir-i18n-routing](https://github.com/vercel/next.js/tree/canary/examples/app-dir-i18n-routing)
+- [with-tailwindcss](https://github.com/vercel/next.js/tree/canary/examples/with-tailwindcss)
+- [with-typescript](https://github.com/vercel/next.js/tree/canary/examples/with-typescript)
 
-TODO
+The main web page renders a list of profiles and shows relevant stats.
+The numbers are taken from a few [YAML](https://en.wikipedia.org/wiki/YAML) files that are stored locally.
+Thanks to React server components, these files can be read directly by the Node.js process and there is no need to introduce any React state to re-hydrate profile infos on the client.
+This simplifies the app architecture and reduces the amount of the JavaScript to download.
+
+Profile infos are updated inside Next.js API routes.
+A GET request to `/update-profiles/[profile-id]?[security-token]` scrapes a third-party service (e.g. GitHub, OpenStreetMap, etc.) and updates a corresponding YAML file.
+Some profile infos are generated by making lightweight requests to JSON endpoints using [Axios](https://axios-http.com) and [Zod](https://zod.dev), but the most common approach involves using [Playwright](https://playwright.dev), a browser automation library.
+Profiles are updated on a schedule (see [Deployment](#deployment) section).
+Because API routes are public, a security token is introduced to prevent server abuse.
 
 ## Known issues
 
-- **Components inside i18n strings**, e.g. `Hello <a>world</a>!`  
-  This is possible with [`<Trans />` component](https://react.i18next.com/latest/trans-component) in `react-i18next` (pending a version that supports `/app` directory and server components).
-- TODO: elaborate on
-  - 404s (permanent solution)
-  - nbprogress
-    - https://github.com/vercel/next.js/issues/45499
-    - https://github.com/apal21/nextjs-progressbar/issues/86
+- **Internationalized (i18n) is hacky**  
+  My go-to solution for internationalising Next.js pages is [`next-i18next`](https://www.npmjs.com/package/next-i18next).
+  Because this package is incompatible with the `/app` directory (at least as of early March 2023), I have used a rather bare-bones approach inspired by the [app-dir-i18n-routing](https://github.com/vercel/next.js/tree/canary/examples/app-dir-i18n-routing) example.
+  The current solution is not as polished as `next-i18next` when it comes to propagating translations to components, but it works well enough for my needs.
+  I might consider following [i18next/next-13-app-dir-i18next-example](https://github.com/i18next/next-13-app-dir-i18next-example) in the future but I am generally waiting for this space to mature.
+
+  In the meantime, I use [`@formatjs/intl`](https://www.npmjs.com/package/@formatjs/intl) to handle plurals, which is somewhat low-level and should not be done in Next.js apps.
+  Ideally, I would like to have i18n resources available as React context and use components inside i18n strings (e.g. `Hello <a>world</a>!`).
+  The latter is possible with [`<Trans />` component](https://react.i18next.com/latest/trans-component) in `react-i18next`, which I hope to use at some point.
+
+- **Custom 404 page is implemented via `middleware.ts`**  
+  As of early March 2023, Next.js [does not support](https://beta.nextjs.org/docs/api-reference/file-conventions/not-found) custom 404 pages inside the `/app` directory.
+  Until a permanent solution is available, incoming requests are checked against `existingPathnamePatterns` in [`middleware.ts`](./middleware.ts).
+  This enables custom 404 pages which are i18n-aware, but requires manual updates to `existingPathnamePatterns` each time a new app route is added.
+  Thus, the workaround is error-prone, especially for apps that have a lot of routes.
+
+- **No progress bar when navigating between pages**  
+  I like using [`nprogress`](https://www.npmjs.com/package/nprogress) in apps with client-side navigation between pages.
+  A progress bar improves the perceived performance of the app and makes it feel more responsive.
+  Unfortunately, `nprogress` does not work well with Next.js apps that use server components.
+  I hope to find a solution to this problem in the future.
+  Related issues:
+  - https://github.com/vercel/next.js/issues/45499
+  - https://github.com/apal21/nextjs-progressbar/issues/86
 
 ## Local development
 
-TODO describe how to run the app locally
+### Getting started
 
-```sh
-pnpm install
-pnpm dev
-```
+1.  Ensure you have [git](https://git-scm.com), [Node.js](https://nodejs.org) and [pnpm](https://pnpm.io) installed on your machine:
 
-## Deployment
+    ```sh
+    git --version
+    ## ≥ 2.30.0
+    
+    node --version
+    ## ≥ 18.12.0
+    
+    pnpm --version
+    ## ≥ 7.28.0
+    ```
+
+1.  Clone the repo from GitHub:
+
+    ```sh
+    cd PATH/TO/MISC/PROJECTS
+    git clone https://github.com/kachkaev/website.git
+    cd website
+    ```
+
+1.  Install dependencies:
+
+    ```sh
+    pnpm install
+    ```
+
+1.  Copy `.env` to `.env.local`:
+
+    ```sh
+    cp .env .env.local
+    ```
+
+    We will need `.env.local` later.
+    Unlike `.env`, it is not tracked by git and is not committed to the repo.
+    Because of that, .env.local` can be used to store secrets.
 
-![thinking meme face](https://gitlab.com/kachkaev/website/uploads/a416ccf87b7a1cd2e2bb386f8109f936/thinking.png)
+1.  Start Next.js in development mode:
+
+    ```sh
+    pnpm dev
+    ```
+
+    This will start the Next.js dev server on `http://localhost:3000`.
+    Modifying source files will refresh the app.
+    To stop running the dev server, press `ctrl+c`.
+
+1.  If you want to try out a production copy of the app, build and run it like this:
+
+    ```sh
+    pnpm build
+    pnpm start
+    ```
+
+### Updating profile infos
+
+If you want to try updating profiles locally, you will need to set `UPDATE_PROFILE_SECURITY_TOKEN` in `.env.local`.
+
+TODO
+
+### Playing with i18n
+
+TODO
+
+## Deployment
 
 TODO describe how to deploy the app
 
+<img src="https://gitlab.com/kachkaev/website/uploads/a416ccf87b7a1cd2e2bb386f8109f936/thinking.png" alt="thinking meme face" width="120" />
+
 ### Docker
 
 ```sh
@@ -66,7 +153,7 @@ docker run \
 
 ### Kubernetes (K8S)
 
-![concentrated meme face](https://gitlab.com/kachkaev/website/uploads/c0799225fbfc40e2c493ed290bc345d1/doing.png)
+<img src="https://gitlab.com/kachkaev/website/uploads/c0799225fbfc40e2c493ed290bc345d1/doing.png" alt="concentrated meme face" width="120" />
 
 #### Namespace
 
@@ -112,7 +199,7 @@ kubectl apply -f k8s/cron-jobs.yaml
 
 All done!
 
-![happy meme face](https://gitlab.com/kachkaev/website/uploads/83aa65c795d488f754a34a4e61d57cfd/done.png)
+<img src="https://gitlab.com/kachkaev/website/uploads/83aa65c795d488f754a34a4e61d57cfd/done.png" alt="happy meme face" width="120" />
 
 To manually update the app deployment, this commands can be used:
 
@@ -157,4 +244,4 @@ If you have questions, feel free to ask me anything by creating a new [GitHub is
 
 The repository is licensed under [BSD-3-Clause license](./LICENSE.md), so you are free to do whatever you want with this stuff!
 
-![thumbs-up meme face](https://gitlab.com/kachkaev/website/uploads/749d5f4679392be346e7e986f2e5e5e1/thumbs-up.png)
+<img src="https://gitlab.com/kachkaev/website/uploads/749d5f4679392be346e7e986f2e5e5e1/thumbs-up.png" alt="thumbs-up meme face" width="160" />