API
This starter kit provides a simple API for managing the state of the application. The API is designed to be easy to use and understand, while also being powerful enough to handle complex use cases.
You can find all the API routes in the app/api folder. The API is built using Next.js and is designed to be easy to use and understand.
Pagefind API
Starting with Nextra v4, the search engine is built-in and uses Pagefind . Unfortunately, the Pagefind API is only available on the client side, from the browser.
In this starter kit, we use a simple trick to make it work on the server side 👏
You can try the API url here
Default route
The default URL is exposed at https://your-site.com/api/search.
Config
The API accepts the following query parameters:
q: The search query.limit: The number of results to return per page (default: 5).excerptLength: The length of the excerpt to return (default: 30).
Anyway, you can change the default values in the config/index.ts file:
...
/**
* Search configuration (for pagefind)
* This is used to configure the search engine API.
* @see /app/api/search/route.ts
*/
search: {
queryKeyword: 'q',
minQueryLength: 3,
limitKeyword: 'limit',
defaultMaxResults: 5,
excerptLengthKeyword: 'excerptLength',
defaultExcerptLength: 30,
defaultLanguage: 'en',
},
...JSON response
Currently, the API returns a JSON response with the following structure:
[
{
"title": "Main Page title",
"content": "Some content",
"items": [
{
"title": "Sub Paragraph title",
"url": "http://yoursite.com/docs/your-docs",
"excerpt": "<mark>Mantine</mark> Components. Here you may use the <mark>Mantine</mark> components: Hello, world!"
}
]
},
...
]In TypeScript, the response is typed as follows:
interface Item {
title: string;
url: string;
excerpt: string;
}
interface Content {
title: string;
content: string;
items: Item[];
}
type Contents = Content[];GitHub Release API
The GitHub Release API is a simple API that allows you to get the latest release of a GitHub repository. It is designed to be easy to use and understand, while also being powerful enough to handle complex use cases.
Have a look at the Release Notes page to see how to use it.
Default route
The default URL is exposed at https://your-site.com/api/github-releases.
Config
You may configure the API in the config/index.ts file:
/**
* GitHub API configuration
* @see https://docs.github.com/en/rest/reference/repos#releases
*
* The GitHub API token is optional for rate limiting.
* If you want to use it, create a personal access token with the `repo` scope.
*
* This information is used to fetch the releases from the GitHub API.
*/
gitHub: {
repo: 'gfazioli/next-app-nextra-template',
apiUrl: 'https://api.github.com',
releasesUrl: 'https://api.github.com/repos/gfazioli/next-app-nextra-template/releases',
},
...
/**
* Release notes configuration
* This is used to link the release notes in the app.
*/
releaseNotes: {
url: 'https://github.com/gfazioli/next-app-nextra-template/releases',
maxReleases: 10,
},
...Rate limiting
The GitHub API has a rate limit of 60 requests per hour for unauthenticated requests. If you want to increase the rate limit, you can create a personal access token with the repo scope and add it to the GITHUB_TOKEN environment variable.
You have to update components/ReleaseNotes/release-notes-toc.ts
...
const releases = await fetcher(
`${config.gitHub.releasesUrl}?per_page=${config.releaseNotes.maxReleases}`
// {
// headers: {
// Authorization: `Bearer ${process.env.GITHUB_TOKEN}`,
// },
// }
).catch((error) => {
// eslint-disable-next-line no-console
console.error('Error fetching releases:', error);
throw error;
});
...and app/api/github-releases/route.ts
...
const response = await fetch(
`${config.gitHub.releasesUrl}?per_page=${config.releaseNotes.maxReleases}`,
{
headers: {
Accept: 'application/vnd.github+json',
// Authorization: `Bearer ${process.env.GITHUB_TOKEN}`, // Optional for rate limit
},
}
);
...