This is a Next.js project bootstrapped with create-next-app.
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 installyarn devOpen 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.
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 starthttps://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
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-tsopenapi-fetch's api client (instantiated in utils/api/client.ts) can then be used to fetch typed data (see docs).
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(forGETrequests), orAPI<endpoint-name>RequestBody(forPOSTrequests), andAPI<endpoint-name>ResponseDatatypes
-
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
fetchNextPageprop fromuseInfiniteQueryit might be necessary to add aPromise<DataType>return type.
- in most cases this should be possible, but if eg. doing some complicated mutation, or using the
- if needed, parsed return types should
- be created from the parser's
ReturnTypeif possible - follow the
Parsed<endpoint-name>Datanaming convention (parsed return consituent item types should begin withParsed, eg.ParsedSearchResult)
- be created from the parser's
- Supported locales are defined in
next-i18next.config.js. - Namespaces are defined in
types/i18next.d.ts.
- Namespace files (with localized content) are created in
public/locales/ - Namespaces are imported with
getI18NextStaticPropsat page level.
- 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).
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="$3" target="_blank" rel="noopener">$1</a>
It's possible, but…
…the initial implementation had more of a maintanence burden than ideal so was shelved at bbec5441a
Static page routes are defined in /routes-i18n.ts which handles URL localization.
When adding a new page / news post, entries for the page need to be added to both of the following objects:
rewrites(used to render pages with localized URLs), androutes(used to creates localized hrefs for the Link component).
If a path contains characters not allowed in the RFC3986 spec (in short a character that isn't an ASCII alphanumeric, /, -, ., _, or ~) it must be percent-encoded which enables fully localized page paths:
`/${encodeURIComponent("ཨོཾ་མུ་ནེ་མུ་ནེ་མ་ཧཱ་མུ་ན་ཡེ་སྭཱ་ཧཱ།")}`;Within mdx files, external links can used the regular markdown link syntax. However internal links should use the Link component with the page directory name as a route prop value to enable i18n route handling. Eg:
<Link route="/news">Nachrichten</Link>For bonus points see:
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!
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!
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.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent