build-react-routes v0.8.0
build-react-routes
Create lightweight routes based on conventions inspired by NextJS App Router.
Usage
npx @tolokoban/build-react-routes ./src/app
The script will watch the given folder and generate an index.tsx
file in it.
You can use it as your main app component:
import { createRoot } from "react-dom/client"
import App from "./app"
createRoot(document.body).render(<App />)
If you want to use nultiple languages, you can pass the current one as a prop:
createRoot(document.body).render(<App lang={navigator.language}/>)
You can get the params from the props or with this hook:
import { useRouteParams } from "./app"
export default function Page({ params }: { params: Record<string, string> }) {
const params2 : Record<string, string> = useRouteParams()
}
The hook is more suited when used inside another hook that do no propagate the params
argument.
Folders conventions
You first have to choose folder to reflect your routes. for instance src/app
.
All subfolders will be pathes of the routes if they contain a page.tsx
or page.mdx
file, with these exceptions:
- Every folder starting with an underscore (
_
) will be ignored. And its content will not be scanned. - Every folder starting with an open parenthesis will not be a path of the route. But its content will be scanned.
Here is an example of folder structure:
src/
┗━ app/
┣━ (articles)/
┃ ┣━ plates/
┃ ┃ ┗━ page.mdx
┃ ┗━ glasses/
┃ ┣━ page.tsx
┃ ┣━ _common_/
┃ ┃ ┣━ config/
┃ ┃ ┃ ┗━ page.tsx
┃ ┃ ┗━ page.tsx
┃ ┣━ beer/
┃ ┃ ┗━ page.mdx
┃ ┣━ wine/
┃ ┗━ juice/
┃ ┗━ page.mdx
┣━ welcome/
┗━ test/
┗━ garbage/
┗━ page.tsx
And here are the resulting routes:
http://localhost/#/plates
http://localhost/#/glasses
http://localhost/#/glasses/beer
http://localhost/#/glasses/juice
http://localhost/#/test/garbage
Filenames conventions
In the src/app
folder (or any other you have specified),
some files have special meanings:
page.tsx
: The component to display when we reach this route. Must export a default function which returns a React component without any property. If a folder contains apage.tsx
, it will generate a route.page.mdx
: Instead of writing the code for the component, you can let MDX generate one based on the Markdown you provide in apage.mdx
file.layout.tsx
: A layout is UI that is shared between multiple pages. On navigation, layouts preserve state, remain interactive, and do not re-render. Layouts can also be nested. Must export a default function which returns a React compoment with achildren: React.ReactNode
property.loading.tsx
: The component to display whilepage.tsx
(orpage.mdx
) is loading.access.ts
: A function to check is the access for this path is authorized.
Authorization
export default async function access(context: {
hash: string,
full: string,
route: string,
params: Record<string, string>
}): Promise<boolean> {
...
}
Multilingual pages
You are supposed to write your website in the "default" language and then add translations if you need them.
For example, if your are writing in english and need an italian translation, you will write page.tsx
and page.it.tsx
.
This works also for layout
and loading
.
The file resolution for en-US
will be to search the files in this order:
page.en-US.mdx
page.en-US.tsx
page.en.mdx
page.en.tsx
page.mdx
page.tsx
Params
Let's look at the file src/app/tasks/[taskId]/page.tsx
:
export default function Page({ params }: { params: Record<string, string> }) {
const taskId = parseInt(params.taskId, 10)
const tasks = listTasks()
const task = tasks[taskId]
return (
<div>
<h1>{task}</h1>
<a href="#..">Back</a>
</div>
)
}
You can notice that the path has an item with square brackets ([taskId]
).
This item matches any string and stores it in a params
object that we can read
in any page.tsx
and layout.tsx
.
Relative paths
If the path does not start with a /
,
that means that it is relative to the current path.
For instance, if you have this folder structure:
src/
┗━ app/
┣━ (articles)/
┗━ glasses/
┣━ page.mdx
┣━ beer/
┃ ┗━ page.mdx
┗━ wine/
┗━ page.mdx
Then you can have this content for src/app/(articles)/glasses/page.mdx
:
# We sell glasses
* (for beer)[#/glasses/beer]
* (for wine)[#/glasses/wine]
but also this one (using relative pathes):
# We sell glasses
* (for beer)[#beer]
* (for wine)[#wine]
Limitations
- Routing works only with hashes.
- Typescript only.
Why don't you just use NextJs or ReactRouter?
If you like the way NextJS deals with routes but cannot afford
to install it in your production environment,
then build-react-routes
can be the cheapest solution.
This solution is best suited for rich documentations written in Markdown.
25 days ago
3 months ago
3 months ago
3 months ago
3 months ago
3 months ago
3 months ago
3 months ago
3 months ago
3 months ago
4 months ago
4 months ago
5 months ago
5 months ago
8 months ago
8 months ago
8 months ago
9 months ago
9 months ago
9 months ago