[RFC] Toolpad core app scaffolding

[Janpot]

Which problem do we want to solve?

• Internal and B2B tooling tend to have different trade-offs in customizability vs developer velocity compared to B2C applications. We target the former with this library.
• Project scaffolding takes a lot of time. Time that is better spent building actual application content.
• Templates contain a lot of boilerplate code. Code which gets added to the project once and never touched. Yet the code has to be maintained for the lifetime of the project. Integration of the different libraries need to be migrated as they progress through major versions.

How will we solve it?

• We provide a project scaffolding CLI. This speeds up the setup time.
• We will support the most commonly used frameworks.
• Combine this with a set of high level components that abstract the highest level building blocks of the application. This is where it differs from templates. We provide high level components so that we can evolve and update these elements over time. It comes at the cost of customizability. Use a template if you need deep customization. High level components include:
  • Application layout
  • Authentication pages
• We will make sure our abstractions allow for static generation, but allow you to use the underlying platform server runtimes if available.

The CLI

Initially we’ll start with a new mode on the create-toolpad-app CLI. Over time this can become the default.

pnpm create toolpad-app --core

The CLI asks questions:

• Which stack?
  • next.js app router (this RFC describes app router)
  • next.js pages router (🚧 future)
  • vite (🚧 future)
• Select authentication providers?
  • Google
  • GitHub
  • …

After completion it generates the following layout in the file system (for Next.js app router):

src/
  app/
    api/
  auth/
  [...nextauth]/
  route.ts
    auth/
      [...path]/
  page.tsx
    (dashboard)/
      page/
  page.tsx
      layout.tsx
    layout.tsx
  theme.ts
next.config.mjs
package.json

Root layout:

The root layout wraps the whole app and provides app wide context.

Responsibilities:

• set up navigation structure provider
• set up adapters for environment (e.g. bridge to app/pages router or react-router)
• set up the theme
• set up branding

// ./src/app/layout.tsx
import { AppProvider } from '@toolpad/core/next-app';
import theme from '../theme';

const NAVIGATION = [
  {
    name: 'page',
    title: 'My Demo Page',
  },
  { kind: 'header', title: 'Sub Header' },
];

function Logo({ size }) {
  return <img src="..." />;
}

const BRANDING = {
  name: 'ACME',
  logo: Logo,
};

export default function Layout({ children }) {
  return (
    <AppProvider branding={BRANDING} navigation={NAVIGATION} theme={theme}>
      {children}
    </AppProvider>
  );
}

The navigation interface:

interface NavigationPageItem {
  kind?: 'page';
  name: string; // route segment
  path: string; // usable in a link
  title: string; // human-readable title
  children: NavigationItem[];
}

interface NavigationSubheaderItem {
  kind: 'header';
  title: string;
}

type NavigationItem = NavigationPageItem | NavigationSubheaderItem;

type navigation = NavigationItem[]

Auth API

https://next-auth.js.org/configuration/initialization#route-handlers-app

We wrap next-auth and initialize its pages property to our custom authentication pages

// ./app/api/auth/[...nextauth]/route.ts
import { createAuthApi } from '@toolpad/core/auth';
import GitHubProvider from '@toolpad/core/auth/github';

const handler = createAuthApi({
  providers: [
    GitHubProvider({
      clientId: process.env.GITHUB_ID,
      clientSecret: process.env.GITHUB_SECRET,
    }),
  ],
});

export { handler as GET, handler as POST };

Auth pages

provides UI for MUI themed [auth pages](https://next-auth.js.org/configuration/pages). exempt from the dashboard layout by placing the latter in a (dashboard) route.

// ./src/app/auth/[...path]/page.tsx
import { AuthPage } from '@toolpad/core/auth';

export default function Page() {
  return <AuthPage />;
}

This will supply next-auth pages for

• /auth/sign-in
• /auth/sign-out
• /auth/error
• /auth/verify-request
• /auth/new-user

We will provide a render prop interface to override the most common UI elements:

• branding
• signInPage
• signOutPage
• …

To provide defaults for each of these customization options we will also export a component per authentication page.

Dashboard layout

• provides UI for navigation (sidebar)
• provides UI for auth (header)
• uses contexts that were set up in ./src/app/layout.tsx
• App Layout component material-ui#14519

// ./src/app/(dashboard)/layout.tsx
import { DashboardLayout } from '@toolpad/core/layout';

export default function Layout({ children }) {
  return <DashboardLayout>{children}</DashboardLayout>;
}

We will add a render prop interface to override the most common UI elements:

• navigation
• header
• branding
• user

Theme

// ./src/theme.tsx
import { ThemeOptions } from '@mui/material';

export default {
  // ...
} satisfies ThemeOptions;