[cli] [docs] Improve tutorial example, docs, CLI installation (#4225)

docs/data/toolpad/core/introduction/TutorialDefault.js

@@ -2,17 +2,23 @@ import * as React from 'react';
 import PropTypes from 'prop-types';
 import { createTheme } from '@mui/material/styles';
 import DashboardIcon from '@mui/icons-material/Dashboard';
+import ShoppingCartIcon from '@mui/icons-material/ShoppingCart';
 import { AppProvider } from '@toolpad/core/AppProvider';
 import { DashboardLayout } from '@toolpad/core/DashboardLayout';
 import { PageContainer } from '@toolpad/core/PageContainer';
 import { useDemoRouter } from '@toolpad/core/internals';
 
 const NAVIGATION = [
   {
-    segment: 'page',
-    title: 'Page',
+    segment: '',
+    title: 'Dashboard',
     icon: <DashboardIcon />,
   },
+  {
+    segment: 'orders',
+    title: 'Orders',
+    icon: <ShoppingCartIcon />,
+  },
 ];
 
 const demoTheme = createTheme({
@@ -33,8 +39,10 @@ const demoTheme = createTheme({
 
 function DemoPageContent({ pathname }) {
   switch (pathname) {
-    case '/page':
+    case '/':
       return <PageContainer>Hello world!</PageContainer>;
+    case '/orders':
+      return <PageContainer>Orders page</PageContainer>;
     default:
       return null;
   }

docs/data/toolpad/core/introduction/TutorialDefault.tsx

@@ -1,6 +1,7 @@
 import * as React from 'react';
 import { createTheme } from '@mui/material/styles';
 import DashboardIcon from '@mui/icons-material/Dashboard';
+import ShoppingCartIcon from '@mui/icons-material/ShoppingCart';
 import { AppProvider } from '@toolpad/core/AppProvider';
 import { DashboardLayout } from '@toolpad/core/DashboardLayout';
 import { PageContainer } from '@toolpad/core/PageContainer';
@@ -9,10 +10,15 @@ import type { Navigation } from '@toolpad/core';
 
 const NAVIGATION: Navigation = [
   {
-    segment: 'page',
-    title: 'Page',
+    segment: '',
+    title: 'Dashboard',
     icon: <DashboardIcon />,
   },
+  {
+    segment: 'orders',
+    title: 'Orders',
+    icon: <ShoppingCartIcon />,
+  },
 ];
 
 const demoTheme = createTheme({
@@ -33,8 +39,10 @@ const demoTheme = createTheme({
 
 function DemoPageContent({ pathname }: { pathname: string }) {
   switch (pathname) {
-    case '/page':
+    case '/':
       return <PageContainer>Hello world!</PageContainer>;
+    case '/orders':
+      return <PageContainer>Orders page</PageContainer>;
     default:
       return null;
   }

docs/data/toolpad/core/introduction/TutorialPages.js

@@ -3,6 +3,7 @@ import PropTypes from 'prop-types';
 import { Typography } from '@mui/material';
 import { createTheme } from '@mui/material/styles';
 import DashboardIcon from '@mui/icons-material/Dashboard';
+import ShoppingCartIcon from '@mui/icons-material/ShoppingCart';
 import TimelineIcon from '@mui/icons-material/Timeline';
 import { AppProvider } from '@toolpad/core/AppProvider';
 import { DashboardLayout } from '@toolpad/core/DashboardLayout';
@@ -15,10 +16,15 @@ const NAVIGATION = [
     title: 'Main items',
   },
   {
-    segment: 'page',
-    title: 'Page',
+    segment: '',
+    title: 'Dashboard',
     icon: <DashboardIcon />,
   },
+  {
+    segment: 'orders',
+    title: 'Orders',
+    icon: <ShoppingCartIcon />,
+  },
   // Add the following new item:
   {
     segment: 'page-2',
@@ -45,8 +51,10 @@ const demoTheme = createTheme({
 
 function DemoPageContent({ pathname }) {
   switch (pathname) {
-    case '/page':
+    case '/':
       return <PageContainer>Hello world!</PageContainer>;
+    case '/orders':
+      return <PageContainer>Orders page</PageContainer>;
     case '/page-2':
       return (
         <PageContainer>

docs/data/toolpad/core/introduction/TutorialPages.tsx

@@ -2,6 +2,7 @@ import * as React from 'react';
 import { Typography } from '@mui/material';
 import { createTheme } from '@mui/material/styles';
 import DashboardIcon from '@mui/icons-material/Dashboard';
+import ShoppingCartIcon from '@mui/icons-material/ShoppingCart';
 import TimelineIcon from '@mui/icons-material/Timeline';
 import { AppProvider } from '@toolpad/core/AppProvider';
 import { DashboardLayout } from '@toolpad/core/DashboardLayout';
@@ -15,10 +16,15 @@ const NAVIGATION: Navigation = [
     title: 'Main items',
   },
   {
-    segment: 'page',
-    title: 'Page',
+    segment: '',
+    title: 'Dashboard',
     icon: <DashboardIcon />,
   },
+  {
+    segment: 'orders',
+    title: 'Orders',
+    icon: <ShoppingCartIcon />,
+  },
   // Add the following new item:
   {
     segment: 'page-2',
@@ -45,8 +51,10 @@ const demoTheme = createTheme({
 
 function DemoPageContent({ pathname }: { pathname: string }) {
   switch (pathname) {
-    case '/page':
+    case '/':
       return <PageContainer>Hello world!</PageContainer>;
+    case '/orders':
+      return <PageContainer>Orders page</PageContainer>;
     case '/page-2':
       return (
         <PageContainer>

docs/data/toolpad/core/introduction/tutorial.md

@@ -19,7 +19,7 @@ npx create-toolpad-app@latest --example core-tutorial
 ```
 
 ```bash pnpm
-pnpm create toolpad-app --example core-tutorial
+pnpm dlx create toolpad-app --example core-tutorial
 ```
 
 ```bash yarn
@@ -51,9 +51,9 @@ yarn && yarn dev
 
 3. The following splash screen appears:
 
-{{"component": "modules/components/DocsImage.tsx", "src": "/static/toolpad/docs/core/installation-1.png", "alt": "Toolpad Core entry point", "caption": "Starting with Toolpad Core", "zoom": true, "indent": 1 }}
+{{"component": "modules/components/DocsImage.tsx", "src": "/static/toolpad/docs/core/bootstrap.png", "srcDark": "/static/toolpad/docs/core/bootstrap-dark.png", "alt": "Toolpad Core entry point", "caption": "Starting with Toolpad Core", "zoom": true, "indent": 1 }}
 
-4. The app has one page already created, which can be viewed by clicking on the "Go to page" button. The following page should appear:
+4. The app has two pages already created in a dashboard layout, with routing, breadcrumbs and theming already set up:
 
 {{"demo": "TutorialDefault.js", "iframe": true, "hideToolbar": true }}
 
@@ -84,15 +84,6 @@ import TimelineIcon from '@mui/icons-material/TimelineIcon';
 // ...
 
 const NAVIGATION: Navigation = [
-  {
-    kind: 'header',
-    title: 'Main items',
-  },
-  {
-    segment: 'page',
-    title: 'Page',
-    icon: <DashboardIcon />,
-  },
   // Add the following new item:
   {
     segment: 'page-2',

examples/core-tutorial/app/(dashboard)/orders/page.tsx

@@ -0,0 +1,6 @@
+import * as React from 'react';
+import Typography from '@mui/material/Typography';
+
+export default function OrdersPage() {
+  return <Typography>Welcome to the Toolpad orders!</Typography>;
+}

examples/core-tutorial/app/(dashboard)/page.tsx

@@ -0,0 +1,11 @@
+import * as React from 'react';
+import Typography from '@mui/material/Typography';
+import Link from 'next/link';
+
+export default function HomePage() {
+  return (
+    <Typography>
+      Welcome to <Link href="https://mui.com/toolpad/core/introduction">Toolpad Core!</Link>
+    </Typography>
+  );
+}

examples/core-tutorial/app/layout.tsx

@@ -1,5 +1,6 @@
 import { AppProvider } from '@toolpad/core/nextjs';
 import DashboardIcon from '@mui/icons-material/Dashboard';
+import ShoppingCartIcon from '@mui/icons-material/ShoppingCart';
 import { AppRouterCacheProvider } from '@mui/material-nextjs/v14-appRouter';
 import type { Navigation } from '@toolpad/core';
 import theme from '../theme';
@@ -10,10 +11,15 @@ const NAVIGATION: Navigation = [
     title: 'Main items',
   },
   {
-    segment: 'page',
-    title: 'Page',
+    segment: '',
+    title: 'Dashboard',
     icon: <DashboardIcon />,
   },
+  {
+    segment: 'orders',
+    title: 'Orders',
+    icon: <ShoppingCartIcon />,
+  },
 ];
 
 export default function RootLayout({ children }: Readonly<{ children: React.ReactNode }>) {

examples/core-tutorial/next-env.d.ts

@@ -2,4 +2,4 @@
 /// <reference types="next/image-types/global" />
 
 // NOTE: This file should not be edited
-// see https://nextjs.org/docs/basic-features/typescript for more information.
+// see https://nextjs.org/docs/app/building-your-application/configuring/typescript for more information.

examples/core-tutorial/package.json

@@ -12,16 +12,15 @@
     "react-dom": "^18",
     "next": "^14",
     "@toolpad/core": "latest",
-    "@mui/material": "^5",
-    "@mui/material-nextjs": "^5",
-    "@mui/icons-material": "^5",
+    "@mui/material": "^6",
+    "@mui/material-nextjs": "^6",
+    "@mui/icons-material": "^6",
     "@emotion/react": "^11",
-    "@emotion/styled": "^11",
-    "@emotion/cache": "^11"
+    "@emotion/styled": "^11"
   },
   "devDependencies": {
     "typescript": "^5",
-    "@types/node": "^20.16.10",
+    "@types/node": "^20",
     "@types/react": "^18",
     "@types/react-dom": "^18",
     "eslint": "^8",

packages/create-toolpad-app/src/index.ts

@@ -173,15 +173,17 @@ const scaffoldCoreProject = async (options: GenerateProjectOptions): Promise<voi
   const files = generateProject(options);
   await writeFiles(options.absolutePath, files);
 
-  // eslint-disable-next-line no-console
-  console.log(`${chalk.cyan('info')} - Installing dependencies`);
-  // eslint-disable-next-line no-console
-  console.log();
+  if (options.install) {
+    // eslint-disable-next-line no-console
+    console.log(`${chalk.cyan('info')} - Installing dependencies`);
+    // eslint-disable-next-line no-console
+    console.log();
 
-  await execa(packageManager, ['install'], { stdio: 'inherit', cwd: options.absolutePath });
+    await execa(packageManager, ['install'], { stdio: 'inherit', cwd: options.absolutePath });
 
-  // eslint-disable-next-line no-console
-  console.log();
+    // eslint-disable-next-line no-console
+    console.log();
+  }
   // eslint-disable-next-line no-console
   console.log(
     `${chalk.green('success')} - Created Toolpad Core project at ${chalk.cyan(options.absolutePath)}`,
@@ -249,6 +251,7 @@ const run = async () => {
   const pathArg = args._?.[0] as string;
   const installFlag = args.install as boolean;
   const studioFlag = args.studio as boolean;
+  const example = args.example as string;
 
   if (pathArg) {
     const pathValidOrError = await validatePath(pathArg);
@@ -266,7 +269,9 @@ const run = async () => {
 
   if (!pathArg) {
     projectPath = await input({
-      message: 'Enter path for new project directory:',
+      message: example
+        ? `Enter path of directory to download example "${chalk.cyan(example)}" into`
+        : 'Enter path of directory to bootstrap new app',
       validate: validatePath,
       default: '.',
     });
@@ -275,8 +280,8 @@ const run = async () => {
   const absolutePath = bashResolvePath(projectPath);
 
   // If the user has provided an example, download and extract it
-  if (args.example) {
-    await downloadAndExtractExample(absolutePath, args.example);
+  if (example) {
+    await downloadAndExtractExample(absolutePath, example);
   }
 
   // If the studio flag is set, create a new project with Toolpad Studio
@@ -331,6 +336,7 @@ const run = async () => {
       coreVersion: args.coreVersion,
       router: routerOption,
       auth: authFlag,
+      install: installFlag,
       authProviders: authProviderOptions,
     };
     await scaffoldCoreProject(options);
@@ -345,7 +351,7 @@ const run = async () => {
       ? `  cd ${path.relative(process.cwd(), absolutePath)}\n`
       : '';
 
-  const installInstruction = installFlag ? '' : `  ${packageManager} install\n`;
+  const installInstruction = example || !installFlag ? `  ${packageManager} install\n` : '';
 
   const message = `Run the following to get started: \n\n${chalk.magentaBright(
     `${changeDirectoryInstruction}${installInstruction}  ${packageManager}${

packages/create-toolpad-app/src/types.ts

@@ -11,6 +11,7 @@ export interface GenerateProjectOptions {
   absolutePath: string;
   auth?: boolean;
   authProviders?: SupportedAuthProvider[];
+  install?: boolean;
   router?: SupportedRouter;
   coreVersion?: string;
   projectType?: ProjectType;