Merge branch 'master' into docs-sdk-edit

docs/embedding/sdk/introduction.md

@@ -10,18 +10,32 @@ With the Embedded analytics SDK, you can embed individual Metabase components wi
 
 ## Example apps built with the embedded analytics SDK
 
-To give you an idea of what's possible with the SDK, we've put together example sites at [metaba.se/sdk-demo](https://metaba.se/sdk-demo). Navigate between different shop websites. Check them out and poke around their products and analytics sections, as well as the New Question and New Dashboard options.
+To give you and idea of what's possible with the SDK, we've put together example sites at [metaba.se/sdk-demo](https://metaba.se/sdk-demo). Navigate between the different shop websites: Proficiency Labs, The Stitch, Luminara Beauty, and Pug & Play. Check them out and poke around their products and [analytics sections](https://embedded-analytics-sdk-demo.metabase.com/admin/analytics/17), as well as the New Question and New Dashboard options.
 
 ![Pug and play example app built with embedding SDK](../images/pug-and-play.png)
 
-Here's the [Shoppy source code](https://github.com/metabase/shoppy).
+To see how we made the demo, check out the [SDK demo's source code](https://github.com/metabase/shoppy).
 
 ## Embedded analytics SDK prerequisites
 
 - React application. The SDK is tested to work with React 18 or higher, though it may work with earlier versions.
 - [Metabase Pro or Enterprise subscription or free trial](https://www.metabase.com/pricing/).
-- Metabase version 1.53 or higher.
-- [Node.js 18.x LTS](https://nodejs.org/en) or higher.
+- Metabase version 1.52 or higher.
+- [Node.js 20.x LTS](https://nodejs.org/en).
+
+## Embedded analytics SDK on NPM
+
+Check out the Metabase Embedded analytics SDK on NPM: [https://www.npmjs.com/package/@metabase/embedding-sdk-react](https://www.npmjs.com/package/@metabase/embedding-sdk-react).
+
+## Quickstart with CLI
+
+If you have Node and Docker installed, you can change into your React application and run:
+
+```sh
+npx @metabase/embedding-sdk-react@latest start
+```
+
+This CLI quickstart only works locally, and you don't need a license key (but you can use one to demo more features).
 
 ## Quickstarts
 
@@ -35,20 +49,25 @@ To use the SDK, you'll need to enable the SDK in Metabase, and install the SDK i
 
 ### Enable the SDK in Metabase
 
-Enable the Embedded analytics SDK by going to **Admin settings > Settings > Embedding**. Toggle on the SDK, and hit **Configure**. Enter the origins for your website or app where you want to allow SDK embedding, separated by a space. Localhost is automatically included.
+Enable the Embedded analytics SDK:
+
+1. Go to **Admin settings > Settings > Embedding**.
+2. Toggle on the SDK.
+3. Hit **Configure**.
+4. Enter the origins for your website or app where you want to allow SDK embedding, separated by a space. Localhost is automatically included.
 
 ### Install the SDK in your React application
 
 You can install the Embedded analytics SDK for React via npm:
 
 ```bash
-npm install @metabase/embedding-sdk-react@51-stable
+npm install @metabase/embedding-sdk-react@53-stable
 ```
 
 or with yarn:
 
 ```bash
-yarn add @metabase/embedding-sdk-react@51-stable
+yarn add @metabase/embedding-sdk-react@53-stable
 ```
 
 ## Developing with the Embedded analytics SDK
@@ -86,7 +105,7 @@ The SDK doesn't support:
 - Subscriptions
 - Alerts
 - Server-side rendering (SSR).
-- Multiple _interactive_ dashboards on the same application page. If you need to embed multiple dashboards on the same application page, you can embed static dashboards.
+- Multiple _interactive_ dashboards on the _same_ application page. If you need to embed multiple dashboards on the same application page, you can embed static dashboards.
 
 ## Feedback
 

docs/embedding/sdk/quickstart-cli.md

@@ -15,6 +15,8 @@ We built a single command to spin up a Metabase and help you get an embedded das
 - License (Optional - only if you want to try out multi-tenancy).
 - Database (you can connect to your app's database).
 
+You don't need a running Metabase; the tool will set up a Metabase for you on Docker.
+
 ## The quickstart command
 
 Change into your React application and run:
@@ -23,33 +25,48 @@ Change into your React application and run:
 npx @metabase/embedding-sdk-react@latest start
 ```
 
-The tool will walk you through the setup. There are a fair number of pieces to put together, so here's an overview of what the command does.
+This CLI tool will walk you through the setup. There are a fair number of pieces to put together, so here's an overview of what the command does:
 
-## Checks for prereqs
+- [Prereq check](#prereq-check)
+- [Database connection (optional)](#database-connection-optional)
+- [Metabase setup](#metabase-setup)
+- [Permissions setup with multi-tenancy (optional)](#permissions-setup-with-multi-tenancy-optional)
+- [React components setup](#react-components-setup)
+- [Behold: Metabase is embedded in your app](#start-your-app)
 
-- Checks that you're installing the SDK in a React application.
-- Looks for, or installs, the Embedded analytics SDK.
-- Checks that Docker is running on your machine.
-- Asks you if you have a database to connect to (use left and right arrow keys to select "no" or "yes"). The tool will use this database to generate an embedded dashboard. If you answer no, the script will use the Sample Database that ships with Metabase to create a dashboard.
+## Prereq check
 
-## Sets up Metabase
+The tool will check for the following:
 
-- Asks you for an email address to create the first admin account in Metabase. Doesn't have to be a real email address (the tool doesn't set up a SMTP server); the email address is just required for login.
-- Spins up a Metabase on Docker. This takes a bit. To see the Docker container's status, use the `docker ps` command. Or use the time to reflect on good choices you've made recently.
-- Generates a new [API key](../../people-and-groups/api-keys.md).
+- You've run the command in the top-level directory of your React application.
+- You've installed the SDK (if you haven't, the CLI will install the SDK for you and add it as a dependency in your `package.json`).
+- You have Docker up and running on your machine.
 
-## Connects Metabase to your database
+## Database connection (optional)
 
-- Prompts you to connect to a database. Pick your database's engine. You'll need the database's host, port, username, and password.
-- Connects to the database, and prompts you to select tables from your database to embed. Pick 1-3 tables. If you want to see multi-tenancy in action, pick a table with user IDs in it. Metabase will X-ray these tables to create a dashboard to embed.
+The tool will ask if you have a database to connect to. Use the arrow keys to select Yes or No. The tool will use this database to generate an embedded dashboard.
 
-## (Optional) sets up permissions with multi-tenancy
+If you answer no, the script will use the Sample Database that ships with Metabase to create a dashboard to embed.
+
+If you select Yes, the tool will prompt you to connect to a database. Pick your database's engine. You'll need to provide database's host, port, username, and password. The tool will connect to the database, and prompt you to select tables from your database to embed. Pick 1-3 tables. If you want to see multi-tenancy in action, pick a table with user IDs in it. Metabase will X-ray these tables to create a dashboard to embed.
+
+## Metabase setup
+
+The tool will ask you for an email address to create the first admin account in Metabase. Doesn't have to be a real email address (the tool doesn't set up a SMTP server); the email address is just required for logging in to the Metabase that the tool will set up.
+
+Next, the tool will spin up a Metabase on Docker. This takes a bit. To see the Docker container's status, use the `docker ps` command. Or use the time to reflect on good choices you've made recently.
+
+Once Metabase is up and running, the tool will create an admin user with the email you provided, and generate an [API key](../../people-and-groups/api-keys.md) for that Metabase.
+
+The tool will then prompt you to pick 1-3 tables to embed. You can press <space> to select, <a> to toggle all, <i> to invert selection, and <enter> to proceed.
+
+## Permissions setup with multi-tenancy (optional)
 
 If you have a Pro/EE license, the tool can set up permissions. To get a license, sign up for a [free trial of self-hosted Metabase Pro](https://www.metabase.com/pricing/).
 
 If you opted to set up multi-tenancy and connected to your own database, the tool will ask you for the column you want to use to sandbox the table (e.g., a user ID column). Metabase will [sandbox data](../../permissions/data-sandboxes.md) based on the values in that column.
 
-The tool will also set up a mock Express server with JWT. It'll ask you where it should save the server code (default: `./mock-server`). It'll install the server's dependencies with `npm install`.
+The tool will also set up a mock Express server to handle the JWTs. The tool will ask you where it should save the server code (default: `./mock-server`). It'll install the server's dependencies with `npm install`.
 
 You'll need to start the mock server in another terminal session. Change into the mock server's directory and run:
 
@@ -57,10 +74,9 @@ You'll need to start the mock server in another terminal session. Change into th
 npm run start
 ```
 
-## Generates React components that you'll import into your app
-
-Generates example React components files. By default, it will save them in `./src/components/metabase` in your React app, though the tool will prompt you to save them to a different directory (e.g., `./src/analytics`).
+## React components setup
 
+Next, the tool will generate example React components files. By default, the tool will save them in `./src/components/metabase` in your React app, though the tool will prompt you to save them to a different directory if you want (e.g., `./src/analytics`).
 It generates a couple of demo components for you to try out theming and user switching:
 
 - `AnalyticsDashboard` - a dashboard component that embeds a Metabase dashboard.
@@ -74,25 +90,33 @@ You can delete these files once you've played around with the tool, and are read
 
 ## Add the Metabase/React components to your app
 
-Once the mock server is running, go back to the tool's terminal session and press <Enter> to continue.
-
-Prompts you to add the following `import` in your client app:
+You'll need to add the Metabase/React components to your app. Add an import to your client app, like so:
 
 ```sh
-import { AnalyticsPage } from "./metabase";
+import { AnalyticsPage } from "./components/metabase/analytics-page";
 ```
 
 Make sure the `from` path is valid (depending on your app, you may need to move the components to a new directory).
 
-Then you'll need to add the `<AnalyticsPage />` component to a page in your app.
+Then you'll need to add the `<AnalyticsPage />` component to a page in your app. Something like:
 
-## Start your app and view the analytics page
+```jsx
+function App() {
+  return (
+    <div className="App" style={{ width: "1200px", height: "800px" }}>
+      <AnalyticsPage/>
+    </div>
+  );
+}
 
-Start your app, and view the page where you added the `<AnalyticsPage />` component, and you should see an embedded dashboard.
+export default App;
+```
 
-## Check out your Metabase
+## Behold: Metabase is embedded in your app
 
-Your Metabase should be running at `http://localhost:3366`. You can find your login credentials at `METABASE_LOGIN.json`.
+Start your app, and visit the page where you added the `<AnalyticsPage />` component. You should see an embedded dashboard.
+
+You can also check out the Metabase the tool set up. The Metabase should be running at `http://localhost:3366`. You can find your login credentials at `METABASE_LOGIN.json`.
 
 ## Further reading