[docs] Add CLI install instructions to docs (#4639)

mui · Feb 12, 2025 · e145f12 · e145f12
1 parent d27e3a9
commit e145f12
Show file tree

Hide file tree

Showing 15 changed files with 132 additions and 54 deletions.
diff --git a/docs/data/toolpad/core/introduction/examples.md b/docs/data/toolpad/core/introduction/examples.md
@@ -7,6 +7,26 @@ title: Examples
 
 <p class="description">Browse a collection of Toolpad Core examples to help you get started quickly.</p>
 
+## Installation
+
+You can create a new project based on any of these examples using the `create-toolpad-app` command:
+
+<codeblock storageKey="package-manager">
+
+```bash npm
+npx create-toolpad-app@latest --example "example-name"
+```
+
+```bash pnpm
+pnpm create toolpad-app --example "example-name"
+```
+
+```bash yarn
+yarn create toolpad-app --example "example-name"
+```
+
+</codeblock>
+
 ## Featured examples
 
 {{"component": "modules/components/examples/CoreFeaturedExamples.tsx"}}

diff --git a/docs/data/toolpad/core/introduction/tutorial.md b/docs/data/toolpad/core/introduction/tutorial.md
@@ -19,7 +19,7 @@ npx create-toolpad-app@latest --example tutorial
 ```
 
 ```bash pnpm
-pnpm dlx create toolpad-app --example tutorial
+pnpm create toolpad-app --example tutorial
 ```
 
 ```bash yarn

diff --git a/docs/src/modules/components/examples/ExamplesFeatured.tsx b/docs/src/modules/components/examples/ExamplesFeatured.tsx
@@ -15,6 +15,9 @@ import CodeRoundedIcon from '@mui/icons-material/CodeRounded';
 import OpenInNewRoundedIcon from '@mui/icons-material/OpenInNewRounded';
 import { useTheme } from '@mui/material/styles';
 import { sxChip } from 'docs/src/modules/components/AppNavDrawerItem';
+import ContentCopyRounded from '@mui/icons-material/ContentCopyRounded';
+import CheckRounded from '@mui/icons-material/CheckRounded';
+import copy from 'clipboard-copy';
 import { Example, versionGitHubLink } from './examplesUtils';
 
 interface FeaturedExamplesProps {
@@ -23,6 +26,13 @@ interface FeaturedExamplesProps {
 
 export default function ExamplesFeatured(props: FeaturedExamplesProps) {
   const t = useTranslate();
+  const [copiedId, setCopiedId] = React.useState<string | null>(null);
+
+  const handleCopy = React.useCallback((text: string, id: string) => {
+    copy(text);
+    setCopiedId(id);
+    setTimeout(() => setCopiedId(null), 2000);
+  }, []);
 
   const examples = props.examples.filter((example: Example) => example.featured === true);
   const docsTheme = useTheme();
@@ -32,6 +42,9 @@ export default function ExamplesFeatured(props: FeaturedExamplesProps) {
       {examples.map((example: Example) => {
         const computedSrc =
           docsTheme?.palette?.mode === 'dark' && example.srcDark ? example.srcDark : example.src;
+        const exampleName = example.source.split('/').pop();
+        const installCommand = `pnpm create toolpad-app --example ${exampleName}`;
+
         return (
           <Box sx={{ display: 'flex', flexDirection: 'column', gap: 1 }} key={example.title}>
             <Typography component="h3" variant="h6" sx={{ fontWeight: 'semiBold' }}>
@@ -160,6 +173,22 @@ export default function ExamplesFeatured(props: FeaturedExamplesProps) {
                     </IconButton>
                   </Tooltip>
                 </Box>
+
+                <Button
+                  size="small"
+                  variant="outlined"
+                  onClick={() => handleCopy(installCommand, example.title)}
+                  startIcon={
+                    copiedId === example.title ? (
+                      <CheckRounded fontSize="small" />
+                    ) : (
+                      <ContentCopyRounded fontSize="small" />
+                    )
+                  }
+                >
+                  {installCommand}
+                </Button>
+
                 <Button
                   component="a"
                   href={example.href}

diff --git a/docs/src/modules/components/examples/ExamplesGrid.tsx b/docs/src/modules/components/examples/ExamplesGrid.tsx
@@ -4,14 +4,16 @@ import Card from '@mui/material/Card';
 import CardActions from '@mui/material/CardActions';
 import CardContent from '@mui/material/CardContent';
 import CardMedia from '@mui/material/CardMedia';
-import Button from '@mui/material/Button';
 import Grid from '@mui/material/Grid';
 import Typography from '@mui/material/Typography';
 import { alpha, useTheme } from '@mui/material/styles';
 import IconButton from '@mui/material/IconButton';
 import Tooltip from '@mui/material/Tooltip';
-import Stack from '@mui/material/Stack';
 import SvgIcon from '@mui/material/SvgIcon';
+import GitHubIcon from '@mui/icons-material/GitHub';
+import ContentCopyRounded from '@mui/icons-material/ContentCopyRounded';
+import CheckRounded from '@mui/icons-material/CheckRounded';
+import copy from 'clipboard-copy';
 import { Example, versionGitHubLink } from './examplesUtils';
 
 interface ExamplesGridProps {
@@ -36,13 +38,22 @@ function CodeSandboxIcon() {
 
 export default function ExamplesGrid(props: ExamplesGridProps) {
   const t = useTranslate();
+  const [copiedId, setCopiedId] = React.useState<string | null>(null);
+
+  const handleCopy = (text: string, id: string) => {
+    copy(text);
+    setCopiedId(id);
+    setTimeout(() => setCopiedId(null), 2000);
+  };
 
   const examples = props.examples.filter((example: Example) => example.featured !== true);
   const docsTheme = useTheme();
 
   return (
     <Grid container spacing={2} sx={{ pt: 2, pb: 4 }}>
       {examples.map((example) => {
+        const exampleName = example.source.split('/').pop();
+        const installCommand = `pnpm create toolpad-app --example ${exampleName}`;
         const computedSrc =
           docsTheme?.palette?.mode === 'dark' && example.srcDark ? example.srcDark : example.src;
         return (
@@ -99,45 +110,63 @@ export default function ExamplesGrid(props: ExamplesGridProps) {
                   p: 0,
                   display: 'flex',
                   alignItems: 'center',
-                  justifyContent: 'space-between',
+                  justifyContent: 'flex-start',
+                  gap: 1,
                 }}
               >
-                <Button
-                  component="a"
-                  href={versionGitHubLink(example.source)}
-                  size="small"
-                  target="_blank"
-                >
-                  {t('source')}
-                </Button>
-                <Stack direction="row" spacing={1}>
-                  {example.stackBlitz === true ? (
-                    <Tooltip title="Edit in StackBlitz">
-                      <IconButton
-                        component="a"
-                        href={`https://stackblitz.com/github/${example.source.replace('https://github.com/', '')}`}
-                        target="_blank"
-                        rel="noopener noreferrer"
-                        size="small"
-                      >
-                        <StackBlitzIcon />
-                      </IconButton>
-                    </Tooltip>
-                  ) : null}
-                  {example.codeSandbox === true ? (
-                    <Tooltip title="Edit in CodeSandbox">
-                      <IconButton
-                        component="a"
-                        href={`https://codesandbox.io/p/sandbox/github/${example.source.replace('https://github.com/', '')}`}
-                        target="_blank"
-                        rel="noopener noreferrer"
-                        size="small"
-                      >
-                        <CodeSandboxIcon />
-                      </IconButton>
-                    </Tooltip>
-                  ) : null}
-                </Stack>
+                <Tooltip title={t('source')}>
+                  <IconButton
+                    component="a"
+                    href={versionGitHubLink(example.source)}
+                    size="small"
+                    target="_blank"
+                  >
+                    <GitHubIcon fontSize="small" />
+                  </IconButton>
+                </Tooltip>
+
+                {example.stackBlitz === true ? (
+                  <Tooltip title="Edit in StackBlitz">
+                    <IconButton
+                      component="a"
+                      href={`https://stackblitz.com/github/${example.source.replace('https://github.com/', '')}`}
+                      target="_blank"
+                      rel="noopener noreferrer"
+                      size="small"
+                    >
+                      <StackBlitzIcon />
+                    </IconButton>
+                  </Tooltip>
+                ) : null}
+
+                {example.codeSandbox === true ? (
+                  <Tooltip title="Edit in CodeSandbox">
+                    <IconButton
+                      component="a"
+                      href={`https://codesandbox.io/p/sandbox/github/${example.source.replace('https://github.com/', '')}`}
+                      target="_blank"
+                      rel="noopener noreferrer"
+                      size="small"
+                    >
+                      <CodeSandboxIcon />
+                    </IconButton>
+                  </Tooltip>
+                ) : null}
+
+                <Tooltip title={installCommand}>
+                  <IconButton
+                    size="small"
+                    onClick={() => {
+                      handleCopy(installCommand, example.title);
+                    }}
+                  >
+                    {copiedId === example.title ? (
+                      <CheckRounded fontSize="small" />
+                    ) : (
+                      <ContentCopyRounded fontSize="small" />
+                    )}
+                  </IconButton>
+                </Tooltip>
               </CardActions>
             </Card>
           </Grid>

diff --git a/examples/core/auth-nextjs-email/README.md b/examples/core/auth-nextjs-email/README.md
@@ -51,7 +51,7 @@ To copy this example and customize it for your needs, run
 ```bash
 npx create-toolpad-app@latest --example auth-nextjs-email
 # or
-pnpm dlx create-toolpad-app --example auth-nextjs-email
+pnpm create toolpad-app --example auth-nextjs-email
 ```
 
 and follow the instructions in the terminal.

diff --git a/examples/core/auth-nextjs-pages-nextauth-4/README.md b/examples/core/auth-nextjs-pages-nextauth-4/README.md
@@ -25,7 +25,7 @@ To copy this example and customize it for your needs, run
 ```bash
 npx create-toolpad-app@latest --example auth-nextjs-pages-nextauth-4
 # or
-pnpm dlx create-toolpad-app --example auth-nextjs-pages-nextauth-4
+pnpm create toolpad-app --example auth-nextjs-pages-nextauth-4
 ```
 
 and follow the instructions in the terminal.

diff --git a/examples/core/auth-nextjs-pages/README.md b/examples/core/auth-nextjs-pages/README.md
@@ -47,7 +47,7 @@ To copy this example and customize it for your needs, run
 ```bash
 npx create-toolpad-app@latest --example auth-nextjs-pages
 # or
-pnpm dlx create-toolpad-app --example auth-nextjs-pages
+pnpm create toolpad-app --example auth-nextjs-pages
 ```
 
 and follow the instructions in the terminal.

diff --git a/examples/core/auth-nextjs-passkey/README.md b/examples/core/auth-nextjs-passkey/README.md
@@ -41,7 +41,7 @@ To copy this example and customize it for your needs, run
 ```bash
 npx create-toolpad-app@latest --example auth-nextjs-passkey
 # or
-pnpm dlx create-toolpad-app --example auth-nextjs-passkey
+pnpm create toolpad-app --example auth-nextjs-passkey
 ```
 
 and follow the instructions in the terminal.

diff --git a/examples/core/auth-nextjs-themed/README.md b/examples/core/auth-nextjs-themed/README.md
@@ -25,7 +25,7 @@ To copy this example and customize it for your needs, run
 ```bash
 npx create-toolpad-app@latest --example auth-nextjs-themed
 # or
-pnpm dlx create-toolpad-app --example auth-nextjs-themed
+pnpm create toolpad-app --example auth-nextjs-themed
 ```
 
 and follow the instructions in the terminal.

diff --git a/examples/core/auth-nextjs/README.md b/examples/core/auth-nextjs/README.md
@@ -35,7 +35,7 @@ GITHUB_CLIENT_SECRET=
 ```bash
 npx auth secret
 # or
-pnpm dlx create-toolpad-app --example auth-nextjs
+pnpm create toolpad-app --example auth-nextjs
 ```
 
 ### GitHub configuration

diff --git a/examples/core/auth-vite/README.md b/examples/core/auth-vite/README.md
@@ -9,7 +9,7 @@ To copy this example and customize it for your needs, run
 ```bash
 npx create-toolpad-app@latest --example auth-vite
 # or
-pnpm dlx create-toolpad-app --example auth-vite
+pnpm create toolpad-app --example auth-vite
 ```
 
 ## Getting Started

diff --git a/examples/core/firebase-vite/README.md b/examples/core/firebase-vite/README.md
@@ -9,7 +9,7 @@ To copy this example and customize it for your needs, run
 ```bash
 npx create-toolpad-app@latest --example firebase-vite
 # or
-pnpm dlx create-toolpad-app --example firebase-vite
+pnpm create toolpad-app --example firebase-vite
 ```
 
 ## Setting up

diff --git a/examples/core/tutorial/README.md b/examples/core/tutorial/README.md
@@ -25,7 +25,7 @@ To copy this example and customize it for your needs, run
 ```bash
 npx create-toolpad-app@latest --example tutorial
 # or
-pnpm dlx create-toolpad-app --example tutorial
+pnpm create toolpad-app --example tutorial
 ```
 
 and follow the instructions in the terminal.

diff --git a/examples/core/vite/README.md b/examples/core/vite/README.md
@@ -9,7 +9,7 @@ To copy this example and customize it for your needs, run
 ```bash
 npx create-toolpad-app@latest --example vite
 # or
-pnpm dlx create-toolpad-app --example vite
+pnpm create toolpad-app --example vite
 ```
 
 and follow the instructions in the terminal.

diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml