Getting Started

This is the documentation for the latest version of Next Admin. If you are using an older version (<5.0.0), please refer to the documentation

The following guide will help you get started with Next-Admin.

The CLI is in its early stages of development and might be the subject of unexpected behaviors. If you encounter any issues, please report them on the GitHub repository.

You can initialize the required files to use Next-Admin in your project using the CLI.

npx @premieroctet/next-admin-cli@latest init

Make sure to check the available options by running the following command:

npx @premieroctet/next-admin-cli@latest init --help

Installation

yarn add @premieroctet/next-admin @premieroctet/next-admin-generator-prisma

npm install -S @premieroctet/next-admin @premieroctet/next-admin-generator-prisma

pnpm add @premieroctet/next-admin @premieroctet/next-admin-generator-prisma

TailwindCSS

Next-Admin relies on TailwindCSS for the style. If you do not have it, you can install TailwindCSS with the following configuration :

tailwind.config.js

module.exports = {
  content: [
    "./node_modules/@premieroctet/next-admin/dist/**/*.{js,ts,jsx,tsx}",
  ],
  darkMode: "class",
  presets: [require("@premieroctet/next-admin/preset")],
};

Then import your .css file containing Tailwind rules into a page file or a parent layout.

You can find more information about theming here

Prisma

Next-Admin relies on Prisma for the database. If you do not have it, you can install Prisma with the following config.

You have to add the jsonSchema generator to your schema.prisma file:

schema.prisma

generator nextAdmin {
  provider = "next-admin-generator-prisma"
}

Then run the following command :

yarn run prisma generate

Page `[[...nextadmin]]`

Next-Admin uses a dynamic route [[...nextadmin]] to handle all the admin routes.

Create file : `page.tsx`

app/admin/[[...nextadmin]]/page.tsx

import { NextAdmin, PageProps } from "@premieroctet/next-admin";
import { getNextAdminProps } from "@premieroctet/next-admin/appRouter";
import { prisma } from "@/prisma";
import "@/styles.css" // .css file containing tailiwnd rules
 
export default async function AdminPage({
  params,
  searchParams,
}: PageProps) { // or PromisePageProps for Next 15+
  const props = await getNextAdminProps({
    params: params.nextadmin,
    searchParams,
    basePath: "/admin",
    apiBasePath: "/api/admin",
    prisma,
    /*options*/
  });
 
  return <NextAdmin {...props}/>;
}

⚠️

Passing the options prop like you’d do on Pages router will result in an error in case you have functions defined inside the options object (formatter, handlers, etc.). Make sure to pass no options prop to NextAdmin component in App router.

⚠️

Make sure to not use use client in the page.

⚠️

Because we are using next-themes to handle dark mode, you will need to add the suppressHydrationWarning to your the closest <html> tag of the admin page. See the next-themes docs

Create file : `[[...nextadmin]].ts`

pages/admin/[[...nextadmin]].ts

import { AdminComponentProps, NextAdmin } from "@premieroctet/next-admin";
 
import { getNextAdminProps } from "@premieroctet/next-admin/pageRouter";
import { GetServerSideProps } from "next";
import { prisma } from " @/prisma";
 
export default function Admin(props: AdminComponentProps) {
  return (
    <NextAdmin
      {...props}
      /*options*/
    />
  );
}
 
export const getServerSideProps: GetServerSideProps = async ({ req }) =>
  await getNextAdminProps({
    basePath: "/pagerouter/admin",
    apiBasePath: "/api/pagerouter/admin",
    prisma,
    /*options*/
    req,
  });

Do not forget to add the options prop to <NextAdmin /> component and getNextAdminProps function, if you are using it.

Your CSS file should be imported in the _app.js / _app.tsx file. This is mandatory per the Next.js documentation. In most apps, you might have a different tailwind configuration living with the Next-Admin one. In that case, to avoid any conflicts, you can create an App Router layout file which imports the CSS file.

SuperJson configuration

SuperJson is required to avoid errors related to invalid serialisation properties that can occur when passing data from server to client.

With Babel

  yarn add -D babel-plugin-superjson-next superjson@^1

  npm install --save-dev babel-plugin-superjson-next superjson@^1

  pnpm install -D babel-plugin-superjson-next superjson@^1

Add the babel-plugin-superjson-next plugin to your .babelrc file:

{
  "presets": ["next/babel"],
  "plugins": ["superjson-next"]
}

With SWC (Experimental)

yarn add -D next-superjson-plugin superjson

npm install --save-dev next-superjson-plugin superjson

pnpm install -D next-superjson-plugin superjson

Add the next-superjson-plugin plugin to your next.config.js file:

module.exports = {
  // your current config
  experimental: {
    swcPlugins: [
      [
        "next-superjson-plugin",
        {
          excluded: [],
        },
      ],
    ],
  },
};

More information about the getNextAdminProps here.

API Route `[[...nextadmin]]`

Next-Admin uses a dynamic route [[...nextadmin]] to handle all the API routes.

app/api/admin/[[...nextadmin]]/route.ts

import { prisma } from "@/prisma";
import { createHandler } from "@premieroctet/next-admin/appHandler";
 
const { run } = createHandler({
  apiBasePath: "/api/admin",
  prisma,
  /*options*/
});
 
export { run as DELETE, run as GET, run as POST };

More information about the createHandler function here.

Next Admin options - optional

The NextAdmin component accepts an optional options prop. In the blocks above, you can see that the options prop is commented out. It may be useful to centralize the options in a single file. More information about the options here.

The options parameter can be set to function/component, if you are using options, be sure to pass the same options to the handler and the router function.

Usage

Once done, you can navigate to the /admin route.

Introduction <NextAdmin/>