feat: adding documentation to docs app (#34)

Makefile

@@ -115,7 +115,7 @@ build:
 .PHONY: build
 
 purge: down
-	rm -rf .pnpm-store node_modules; \
+	rm -rf .pnpm-store node_modules && \
 	rm -rf **/node_modules pnpm-lock.yaml **/.turbo **/.next
 .PHONY: purge
 

README.md

@@ -11,7 +11,7 @@
 
 <div align="center">
 <a href="https://actions-badge.atrox.dev/wayofdev/next-starter-tpl/goto"><img alt="Build Status" src="https://img.shields.io/endpoint.svg?url=https%3A%2F%2Factions-badge.atrox.dev%2Fwayofdev%2Fnext-starter-tpl%2Fbadge&style=flat-square"/></a>
-<a href="https://github.com/wayofdev/next-starter-tpl/tags"><img src="https://img.shields.io/github/v/tag/wayofdev/next-starter-tpl?sort=semver&style=flat-square" alt="Latest Version"></a>
+<a href="https://github.com/wayofdev/next-starter-tpl/tags"><img alt="GitHub package.json version" src="https://img.shields.io/github/package-json/v/wayofdev/next-starter-tpl?style=flat-square"></a>
 <a href="LICENSE.md"><img src="https://img.shields.io/github/license/wayofdev/next-starter-tpl.svg?style=flat-square&color=blue" alt="Software License"/></a>
 <a href="#"><img alt="Commits since latest release" src="https://img.shields.io/github/commits-since/wayofdev/next-starter-tpl/latest?style=flat-square"></a>
 <a href="https://codeclimate.com/github/wayofdev/next-starter-tpl"><img alt="Code Climate maintainability" src="https://img.shields.io/codeclimate/maintainability/wayofdev/next-starter-tpl?style=flat-square"></a>
@@ -24,23 +24,46 @@
 
 # NextJS Starter Template
 
-This repository contains [monorepo](https://turbo.build/repo/docs/handbook/what-is-a-monorepo) boilerplate written in [Next.js](https://nextjs.org). Used together with backend API part — [laravel-starter-tpl](https://github.com/wayofdev/laravel-starter-tpl).
+## 📄 About
+
+This repository contains a [monorepo](https://turbo.build/repo/docs/handbook/what-is-a-monorepo) boilerplate written in [Next.js](https://nextjs.org/), managed by the [pnpm](https://pnpm.io) package manager.
+
+You can use it with the backend template, written in Laravel — [laravel-starter-tpl](https://github.com/wayofdev/laravel-starter-tpl).
+
+### → Purpose
+
+- Establish a **structure** and present a lifecycle perspective (dx, ci/cd, deployments);
+- Show how to create and consume shared packages, locales, assets, and API types;
+- Ship fully configured repository with integrated **tools & configs**, like tsconfig, eslint, jest, cypress, tailwind, changelogs, versioning, codecov, codeclimate, sentry, and others;
+- Clarify some **advantages** of monorepo (team cohesion, consistency, duplication, refactorings, atomic commits)
 
 <br>
 
 ## 🤔 What's inside?
 
 This turborepo uses [pnpm](https://pnpm.io) as a package manager. It includes the following packages/apps:
 
-### → Apps and Packages
+### → Apps
+
+- `docs`: a [Nextra](https://nextra.site/) documentation template generated from [Nextra: Docs Starter Kit](https://vercel.com/templates/next.js/documentation-starter-kit)
+
+  - [DEMO docs app](https://next-starter-tpl-docs.vercel.app/)
 
-- `docs`: a [Nextra](https://nextra.site/) application generated from [Nextra: Docs Starter Kit](https://vercel.com/templates/next.js/documentation-starter-kit)
-- `web`: [Next.js](https://nextjs.org/) app
-- `ui`: a stub React component library shared by both `web` and `docs` applications
+- `web`: [Next.js](https://nextjs.org/) app with tailwindcss and sentry support
+
+  - [DEMO web app](https://next-starter-tpl-web.vercel.app/)
+
+- `ui`: a stub React component library shared by the `web` application
+
+> **Note:** Apps should not depend on apps, they can depend on packages
+
+### → Packages
+
+- `common-i18n`: locales for multi-language support
 - `eslint-config-custom`: `eslint` configurations (includes `eslint-config-next` and `eslint-config-prettier`)
-- `tsconfig-config`: `tsconfig` configs used throughout the monorepo
 - `jest-config`: [JestJS](https://jestjs.io) configs used across the monorepo
-- Each package/app is 100% [TypeScript](https://www.typescriptlang.org/).
+
+> **Note:** Apps can depend on packages, packages can depend on each others
 
 <br>
 
@@ -69,7 +92,7 @@ This repository has some additional tools already setup for you:
 
 <br>
 
-## 📑 Requirements
+## 🚩 Requirements
 
 - **macOS** Monterey+ or **Linux**
 - **Docker** 20.10 or newer

apps/docs/.eslintrc.js

@@ -37,12 +37,4 @@ module.exports = {
     // https://github.com/jsx-eslint/eslint-plugin-jsx-a11y/blob/HEAD/docs/rules/anchor-is-valid.md
     'jsx-a11y/anchor-is-valid': 'off',
   },
-  overrides: [
-    {
-      files: ['src/pages/\\_*.{ts,tsx}'],
-      rules: {
-        'react/display-name': 'off',
-      },
-    },
-  ],
 }

apps/docs/package.json

@@ -14,8 +14,8 @@
   "dependencies": {
     "@wayofdev/ui": "workspace:*",
     "next": "^13.1.1",
-    "nextra": "^2.0.3",
-    "nextra-theme-docs": "^2.0.3",
+    "nextra": "^2.1.0",
+    "nextra-theme-docs": "^2.1.0",
     "react": "^18.2.0",
     "react-dom": "^18.2.0"
   },

apps/docs/pages/_app.tsx

@@ -0,0 +1,8 @@
+import type { AppProps } from 'next/app'
+import type { ReactElement } from 'react'
+
+import '../style.css'
+
+export default function Nextra({ Component, pageProps }: AppProps): ReactElement {
+  return <Component {...pageProps} />
+}

apps/docs/pages/_meta.json

@@ -1,11 +1,6 @@
 {
   "index": "Introduction",
-  "another": "Another Page",
-  "advanced": "Advanced (A Folder)",
-  "about": {
-    "title": "About",
-    "type": "page"
-  },
+  "guide": "Guide",
   "contact": {
     "title": "Contact ↗",
     "type": "page",

apps/docs/pages/guide.mdx

@@ -0,0 +1,3 @@
+# Guide
+
+This is the index page for the Guide folder!

apps/docs/pages/guide/getting-started.mdx

@@ -0,0 +1,112 @@
+import { Callout } from 'nextra-theme-docs'
+
+## 🚩 Requirements
+
+- **macOS** Monterey+ or **Linux**
+- **Docker** 20.10 or newer
+- [How To Install and Use Docker on Ubuntu 22.04](https://www.digitalocean.com/community/tutorials/how-to-install-and-use-docker-on-ubuntu-22-04)
+- **Cloned, configured and running** [docker-shared-services](https://github.com/wayofdev/docker-shared-services), to support system-wide DNS, Routing and TLS support via Traefik.
+
+## 💨 Quick Start from Template
+
+### → Fork and Deploy to Vercel
+
+You can start by creating your monorepo with web and docs applications by deploying to Vercel by clicking the link:
+
+[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fwayofdev%2Fnext-starter-tpl%2Ftree%2Fmaster)
+
+### → Manual Setup
+
+You can use GitHub built-in functionality, to generate your repository from this template. Generated repository can always be synced using [manual GitHub workflow](https://github.com/wayofdev/next-starter-tpl/blob/master/.github/workflows/sync-from-tpl.yml).
+
+- Open this repository template in GitHub - [wayofdev/next-starter-tpl](https://github.com/wayofdev/next-starter-tpl)
+- Click on the [Use this template](https://github.com/wayofdev/next-starter-tpl/generate) button
+- Enter repository name, select repository visibility
+- Click on the **Create repository from template** button
+- To periodically sync your repository from upstream, use [manual GitHub workflow](https://github.com/wayofdev/next-starter-tpl/actions/workflows/sync-from-tpl.yml). `.templatesyncignore` file can be used to ignore files from syncing. More info about syncing can be found in [AndreasAugustin/actions-template-sync](https://github.com/AndreasAugustin/actions-template-sync)
+
+### → Using Terraform
+
+At WoD we use Terraform to automate the process of creating new repositories from templates. [mineiros-io/terraform-github-repository](https://github.com/mineiros-io/terraform-github-repositor) repository can be used, to manage your GitHub organization state, all repositories and their templates.
+
+Example configuration for creating new repository from template:
+
+```hcl filename="repos-frontend.tf"
+module "repository_next_frontend_[project-name]" {
+  source  = "mineiros-io/repository/github"
+  version = "~> 0.18.0"
+
+  name         = "next-frontend-[project-name]"
+  description  = "NextJS based frontend application for [project-name]"
+  visibility   = "private"
+  homepage_url = "https://[project-name].io"
+  push_teams   = [module.team_vb.id]
+  admin_teams  = [module.team_infra.id]
+
+  template = {
+    include_all_branches = true
+    owner                = "wayofdev"
+    repository           = "next-starter-tpl"
+  }
+
+  branches = [
+    {
+      name          = "develop"
+      source_branch = "master"
+    },
+  ]
+
+  default_branch = "develop"
+
+  branch_protections_v4 = [
+    {
+      pattern = "master"
+    },
+    {
+      pattern                         = "develop"
+      require_conversation_resolution = true
+
+      required_pull_request_reviews = {
+        require_code_owner_reviews      = false
+        required_approving_review_count = 0
+      }
+    }
+  ]
+
+  issue_labels                          = tolist(local.default_issue_labels)
+  issue_labels_merge_with_github_labels = false
+}
+```
+
+## 💻 Setup
+
+<Callout type="warning">
+  Repository with [docker-shared-services](https://github.com/wayofdev/docker-shared-services)
+  should be configured, up and running, to ensure `*.docker` domain support system-wide.
+</Callout>
+
+<div className="steps-container">
+
+### → Clone Repository
+
+After forking or creating generating repository from template, you can clone it to your local machine. In this example we will use `next-starter-tpl` repository as starting point.
+
+```bash
+$ git clone [email protected]:wayofdev/next-starter-tpl.git
+```
+
+### → Generate `.env` file
+
+Generate .env file from .env.example file.
+
+```bash
+# add FORCE=true to overwrite existing .env file
+$ make env \
+  APP_NAME=tpl \
+  SHARED_SERVICES_NAMESPACE=ss \
+  PROJECT_SERVICES_NAMESPACE=wod
+```
+
+Change generated `.env` file to match your needs, if needed.
+
+</div>

apps/docs/pages/index.mdx

@@ -1,11 +1,65 @@
-# Introduction
+import { Callout } from 'nextra-theme-docs'
 
-Welcome to Nextra! This is a basic docs template. You can use it as a starting point for your own project :)
+# NextJS Starter Template
 
-## What is Nextra?
+## 📄 About
 
-A **simple**, **powerful** and **flexible** site generation framework with everything you love from Next.js.
+This repository contains a [monorepo](https://turbo.build/repo/docs/handbook/what-is-a-monorepo) boilerplate written in [Next.js](https://nextjs.org/), managed by the [pnpm](https://pnpm.io) package manager.
 
-## Documentation
+You can use it with the backend template, written in Laravel — [laravel-starter-tpl](https://github.com/wayofdev/laravel-starter-tpl).
 
-The documentation is available at [https://nextra.site](https://nextra.site).
+### → Purpose
+
+- Establish a **structure** and present a lifecycle perspective (dx, ci/cd, deployments);
+- Show how to create and consume shared packages, locales, assets, and API types;
+- Ship fully configured repository with integrated **tools & configs**, like tsconfig, eslint, jest, cypress, tailwind, changelogs, versioning, codecov, codeclimate, sentry, and others;
+- Clarify some **advantages** of monorepo (team cohesion, consistency, duplication, refactorings, atomic commits)
+
+## 🤔 What's inside?
+
+[![Open in Gitpod](https://img.shields.io/badge/Open%20In-Gitpod.io-%231966D2?style=for-the-badge&logo=gitpod)](https://gitpod.io/#https://github.com/wayofdev/next-starter-tpl)
+
+This turborepo uses [pnpm](https://pnpm.io) as a package manager. It includes the following packages/apps:
+
+### → Apps
+
+| Name        | URL                                                  | Description                                                                                                                                                     |
+| ----------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `apps/docs` | 🌎 [Demo](https://next-starter-tpl-docs.vercel.app/) | [Nextra](https://nextra.site/) documentation template generated from [Nextra: Docs Starter Kit](https://vercel.com/templates/next.js/documentation-starter-kit) |
+| `apps/web`  | 🌎 [Demo](https://next-starter-tpl-web.vercel.app/)  | [Next.js](https://nextjs.org/) app with tailwindcss and sentry support.                                                                                         |
+
+<Callout type="note">Apps should not depend on apps, they can depend on packages.</Callout>
+
+### → Packages
+
+| Name                            | Description                                                                          |
+| ------------------------------- | ------------------------------------------------------------------------------------ |
+| `packages/ui`                   | a stub React component library shared by the `web` application                       |
+| `packages/common-i18n`          | locales for multi-language support                                                   |
+| `packages/eslint-config-custom` | `eslint` configurations (includes `eslint-config-next` and `eslint-config-prettier`) |
+| `packages/jest-config`          | [JestJS](https://jestjs.io) configs used across the monorepo                         |
+
+<Callout type="note">Apps can depend on packages, packages can depend on each others.</Callout>
+
+### → Utilities and Features
+
+This repository has some additional tools already setup for you:
+
+- Supporting [NextJS 13.1.1+](https://nextjs.org/blog/next-13)
+- [TypeScript](https://www.typescriptlang.org/) support for static type checking
+- Strict Mode for TypeScript and React 18
+- [ESLint](https://eslint.org/) for code linting and configured presets: NextJS Recommended, NextJS Core Web Vitals and [Airbnb Style Guide](https://www.npmjs.com/package/eslint-config-airbnb)
+- Code formatting with [Prettier](https://prettier.io/)
+- Integrated with [Tailwind CSS](https://tailwindcss.com/)
+- [PostCSS](https://postcss.org/) for processing Tailwind CSS and [CSSNANO](https://cssnano.co/) for CSS optimization on production systems
+- [Husky](https://typicode.github.io/husky/#/) for modern native git hooks
+- [Lint-staged](https://github.com/okonet/lint-staged) for running linters on Git staged files
+- [GitHub Actions](https://github.com/features/actions) support out of the box
+- SEO metadata, JSON-LD and Open Graph tags with [Next SEO](https://github.com/garmeeh/next-seo)
+- Sitemap support using [next-sitemap](https://www.npmjs.com/package/next-sitemap)
+- [Bundler Analyzer](https://www.npmjs.com/package/@next/bundle-analyzer) — Visualize size of webpack output files with an interactive zoomable treemap
+- Optimized [Lighthouse](https://web.dev/performance-scoring/) performance score
+- End-2-end testing with [cypress](https://www.cypress.io/) and [JestJS](https://jestjs.io/) support for writing unit tests
+- Package auto-update in all workspace projects using [npm-check-updates](https://www.npmjs.com/package/npm-check-updates)
+- Keep package.json sorted using [sort-package-json](https://www.npmjs.com/package/sort-package-json)
+- Client and server side [error reporting](https://sentry.io/) supported by [@sentry/nextjs](https://www.npmjs.com/package/@sentry/nextjs)