This is a Next.js project bootstrapped with create-next-app.

Getting Started

First, run the development server (make sure to use yarn and not npm*!):

*note: the project doesn't use yarn classic (it's been deprecated), so install yarn if needed: https://yarnpkg.com/getting-started/install

corepack enable # if needed
yarn install

Dev mode:

yarn dev

Open http://localhost:3000 with your browser to see the result.

You can start editing the page by modifying pages/index.tsx. The page auto-updates as you edit the file.

API routes can be accessed on http://localhost:3000/api/hello. This endpoint can be edited in pages/api/hello.ts.

The pages/api directory is mapped to /api/*. Files in this directory are treated as API routes instead of React pages.

Building locally:

The project generates many, many static pages which in most cases will preclude the possibility of running a normal build locally.

It is possible to use the compile mode locally:

yarn build:compile
yarn start

API BE<>FE intergration

https://buddhanexus2.kc-tbts.uni-hamburg.de/api/docs#/ (as an intrim measure the BN api is hosted at https://dharmamitra.org/api-db/docs#/ with the api model available at https://dharmamitra.org/api-db/openapi.json)

The utils/api/endpoints directory mirrors the BE api endpoint structure

API type code generation & API Client

The project uses openapi-typescript and openapi-fetch to interface between the backend.

Types are generated from the API project's OpenAPI docs page by running:

yarn openapi-ts

openapi-fetch's api client (instantiated in utils/api/client.ts) can then be used to fetch typed data (see docs).

API type files & conventions

note: at the time of writing, there is still some inconsistency in BE naming conventions. Some FE parsing needs may be eliminated with BE consistency. Review an update accordingly.

• utils/api/types.ts:

  • this is the source of truth for BE<>FE typing
  • it contains codegen derivate types only to create shortened, standardized API type aliases
  • all types begin with API
  • all endpoints should have corresponding API<endpoint-name>RequestQuery (for GET requests), or API<endpoint-name>RequestBody (for POST requests), and API<endpoint-name>ResponseData types

• utils/api/endpoints/<endpoint-name>.ts:

  • co-locates endpoint fetch function and, if required, its return type.
  • inferred return types are favoured
  • in most cases this should be possible, but if eg. doing some complicated mutation, or using the fetchNextPage prop from useInfiniteQuery it might be necessary to add a Promise<DataType> return type.
  • if needed, parsed return types should
  • be created from the parser's ReturnType if possible
  • follow the Parsed<endpoint-name>Data naming convention (parsed return consituent item types should begin with Parsed, eg. ParsedSearchResult)

I18n

• Supported locales are defined in next-i18next.config.js.
• Namespaces are defined in types/i18next.d.ts.

tsx pages

• Namespace files (with localized content) are created in public/locales/
• Namespaces are imported with getI18NextStaticProps at page level.

mdx pages

• Pages for each supported locale are created in content/pages (or a dedicated content directory for nested routes eg. news). See: MDX page i18n for more.

Note: the project uses the term locale to refer to the user's language and the term language to refer to database languages (Pali, Sanskrit, Chinese and Tibetan).

MDX page i18n (Draft)

Static pages built from mdx files are held in /content/. Each page has a dedicated directory containing localized mdx files for supported locals:

├── content
    ├── news
    │   ├── author-and-translators-identification-inittiative
    │   │   ├── de.mdx
    │   │   └── en.mdx
    …
    └── pages
        ├── contact
        │   ├── de.mdx
        │   └── en.mdx
        ├── events
        │   ├── de.mdx
        │   └── en.mdx
        …

Content files must contain frontmatter following the schema defined in the MDXFrontmatter interface.

So that external link open in new tabs it is necessary to use regular html a elements with target="_blank" rel="noopener" attributes.

Original native mdx links have been converted with:

\[((.*?\n?){0,4})\]\((\s*?http(.*?\n?){0,4})\)
<a href="https://github.com/BuddhaNexus/buddhanexus-frontend-next/blob/main/$3" target="_blank" rel="noopener">$1</a>

Localized URLs

JSX components & imports

These can be used in mdx files, by declaring them through the optional components, imports & props frontmatter properties and importing them in utils/mdxPageImports.ts. These will then be passed to MDXRemote in the page template file, which renders compiled source from next-mdx-remote's serializer (see pages/[slug].tsx).

It might be worth sanity checking this implementation. Heed the wisdom of the readme!

Learn More about Next.js

To learn more about Next.js, take a look at the following resources:

• Next.js Documentation - learn about Next.js features and API.
• Learn Next.js - an interactive Next.js tutorial.

You can check out the Next.js GitHub repository - your feedback and contributions are welcome!

Deploy on Vercel

The easiest way to deploy your Next.js app is to use the Vercel Platform from the creators of Next.js.

Check out our Next.js deployment documentation for more details.