@vendure/docs 0.0.0-202601161541

package/docs/guides/getting-started/installation/index.md

@@ -0,0 +1,234 @@
+---
+title: 'Installation'
+sidebar_position: 1
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+## Requirements
+
+- [Node.js](https://nodejs.org/en/) **v20**, **v22** and **v24** - these versions are tested and supported. (Odd-numbered versions above v20 should still work but are not officially supported.)
+
+### Optional
+
+- [Docker Desktop](https://www.docker.com/products/docker-desktop/): If you want to use the quick start with Postgres, you must have Docker Desktop installed. If you do not have Docker Desktop installed, then SQLite will be used for your database.
+- If you want to use an existing MySQL, MariaDB, or Postgres server as your data store, then you'll need an instance available locally. However, **if you are just testing out Vendure, we recommend the quick start option, which handles the database for you**.
+
+## @vendure/create
+
+The recommended way to get started with Vendure is by using the [@vendure/create](https://github.com/vendurehq/vendure/tree/master/packages/create) tool. This is a command-line tool which will scaffold and configure your new Vendure project and install all dependencies.
+
+### Quick Start
+
+First, run the following command in your terminal, replacing `my-shop` with the name of your project:
+
+```bash
+npx @vendure/create my-shop
+```
+
+Next, choose the "Quick Start" option. This is the fastest way to get a Vendure server up and running and will handle all the configuration for you.
+If you have Docker Desktop installed, it will create and configure a Postgres database for you. If not, it will use SQLite.
+
+```text
+┌  Let's create a Vendure App ✨
+│
+◆  How should we proceed?
+// highlight-next-line
+│  ● Quick Start (Get up and running in a single step)
+│  ○ Manual Configuration
+└
+```
+
+Next you'll be prompted to include our official Next.js storefront starter in your project. This is optional, but recommended if you want to
+quickly see a working storefront connected to your Vendure server.
+
+```text
+┌  Let's create a Vendure App ✨
+│
+◇  How should we proceed?
+│  Quick Start
+│
+◇  Using port 3000
+│
+◇  Docker is running
+│
+// highlight-start
+◆  Would you like to include the Next.js storefront?
+│  ○ No
+│  ● Yes
+└
+// highlight-end
+```
+
+And that's it! After a minute or two, you'll have a **fully-functional Vendure server** installed locally.
+
+Once the installation is done, your terminal will output a message indicating a successful installation with:
+
+- The URL to access the **Dashboard**
+- Your admin log-in credentials
+- The project file path
+
+Proceed to the [Start the server](#start-the-server) section below to run your Vendure server.
+
+### Manual Configuration
+
+If you'd rather have more control over the configuration, you can choose the "Manual Configuration" option. This will prompt you to select a database and whether to populate the database with sample data.
+
+#### 1. Select a database
+
+Vendure supports a number of different databases. The `@vendure/create` tool will prompt you to select one.
+
+**To quickly test out Vendure, we recommend using SQLite**, which requires no external dependencies. You can always switch to a different database later [by changing your configuration file](/guides/developer-guide/configuration/#connecting-to-the-database).
+
+```text
+┌  Let's create a Vendure App ✨
+│
+◇  How should we proceed?
+│  Manual Configuration
+│
+◇  Using port 3000
+│
+◆  Which database are you using?
+│  ○ MySQL
+│  ○ MariaDB
+│  ○ Postgres
+// highlight-next-line
+│  ● SQLite
+└
+```
+
+:::tip
+If you select MySQL, MariaDB, or Postgres, you need to make sure you:
+
+1. **Have the database server running**: You can either install the database locally on your machine, use a cloud provider, or run it via Docker. For local development with Docker, you can use the provided `docker-compose.yml` file in your project.
+
+2. **Have created a database**: Use your database client to create an empty database (e.g., `CREATE DATABASE vendure;` in most SQL databases).
+
+3. **Have database credentials**: You need the username and password for a database user that has full permissions (CREATE, ALTER, DROP, INSERT, UPDATE, DELETE, SELECT) on the database you created.
+
+For detailed database configuration examples, see the [Configuration guide](/guides/developer-guide/configuration/#connecting-to-the-database).
+
+:::
+
+#### 2. Populate with data
+
+The final prompt will ask whether to populate your new Vendure server with some sample product data.
+
+**We recommend you do so**, as it will give you a good starting point for exploring the APIs, which we will cover in the [Try the API section](/guides/getting-started/try-the-api/), as well as providing some data to use when building your own storefront.
+
+```text
+┌  Let's create a Vendure App ✨
+│
+◇  How should we proceed?
+│  Manual Configuration
+│
+// ...
+│
+◆  Populate with some sample product data?
+// highlight-next-line
+│  ● yes
+│  ○ no
+└
+```
+
+#### 3. Optional storefront setup
+
+From v3.5.2 onwards, you can choose to include an official Next.js Storefront Starter as part of your new Vendure project.
+
+#### 4. Complete setup
+
+Next, a project scaffold will be created and dependencies installed. This may take a few minutes.
+
+Once complete, you'll see a message like this:
+
+```text
+◇  Setup complete! ─────────────────────────────────────╮
+│                                                       │
+│  Your new Vendure project was created!                │
+│  /Users/username/path/my-shop                         │
+│                                                       │
+│                                                       │
+│  This is a monorepo with the following apps:          │
+│    apps/server     - Vendure backend                  │
+│    apps/storefront - Next.js frontend                 │
+│                                                       │
+│                                                       │
+│  Next, run:                                           │
+│  $ cd my-shop                                         │
+│  $ npm run dev                                        │
+│                                                       │
+│                                                       │
+│  This will start both the server and storefront.      │
+│                                                       │
+│                                                       │
+│  Access points:                                       │
+│    Dashboard:  http://localhost:3000/dashboard        │
+│    Storefront: http://localhost:3001                  │
+│                                                       │
+│                                                       │
+│  Use the following credentials to log in:             │
+│  Username: superadmin                                 │
+│  Password: superadmin                                 │
+│                                                       │
+│                                                       │
+│  ➡️ Docs: https://docs.vendure.io                     │
+│  ➡️ Discord community: https://vendure.io/community   │
+│  ➡️ Star us on GitHub:                                │
+│     https://github.com/vendurehq/vendure      │
+│                                                       │
+├───────────────────────────────────────────────────────╯
+│
+└  Happy hacking!
+```
+
+### Start the server
+
+Follow the instructions to move into the new directory created for your project, and start the server:
+
+```bash
+cd my-shop
+
+npm run dev
+```
+
+You should now be able to access:
+
+- The Vendure Admin GraphQL API: [http://localhost:3000/admin-api](http://localhost:3000/admin-api)
+- The Vendure Shop GraphQL API: [http://localhost:3000/shop-api](http://localhost:3000/shop-api)
+- The Vendure Dashboard: [http://localhost:3000/dashboard](http://localhost:3000/dashboard/)
+
+If you included the Next.js Storefront Starter, you can also access:
+
+- The Next.js Storefront: [http://localhost:3001](http://localhost:3001/)
+
+![Running apps](./app-screens.webp)
+
+Congratulations! 🥳 You now have a fully functional Vendure server running locally.
+
+Now you can explore Vendure by following our [Try the API guide](/guides/getting-started/try-the-api/) to learn how to interact with the server.
+
+If you are new to GraphQL, you should also check out our [Introducing GraphQL guide](/guides/getting-started/graphql-intro/).
+
+:::tip
+Open the Dashboard at [http://localhost:3000/dashboard](http://localhost:3000/dashboard) in your browser and log in with the superadmin credentials you specified, which default to:
+
+- **username**: superadmin
+- **password**: superadmin
+
+:::
+
+:::cli
+Use `npx vendure add` to start adding plugins & custom functionality to your Vendure server.
+:::
+
+### Troubleshooting
+
+- If you encounter any issues during installation, you can get a more detailed output by setting the log level to `verbose`:
+
+    ```sh
+    npx @vendure/create my-shop --log-level verbose
+    ```
+
+- The [supported TypeScript version](https://github.com/vendurehq/vendure/blob/master/packages/create/src/constants.ts#L7) is set upon installation. Upgrading to a newer version of TypeScript might result in compilation errors because TypeScript sometimes introduces stricter checks in newer versions.
+- If you want to use **Yarn**, from Vendure v2.2.0+, you'll need to use **Yarn 2** (Berry) or above.

package/docs/guides/getting-started/try-the-api/index.mdx

@@ -0,0 +1,238 @@
+---
+title: 'Try the API'
+---
+
+
+import Playground from '@site/src/components/Playground';
+
+Once you have successfully installed Vendure locally following the [installation guide](/guides/getting-started/installation),
+it's time to try out the API!
+
+:::note
+This guide assumes you chose to populate sample data when installing Vendure.
+
+You can also follow along with these example using the public demo playground at [demo.vendure.io/graphiql/shop](https://demo.vendure.io/graphiql/shop)
+:::
+
+## GraphiQL Interface
+
+Vendure comes with GraphiQL - a powerful UI for exploring and testing GraphQL APIs. It allows you to run queries and mutations
+against both the Shop and Admin APIs, making it easy to explore the API and understand how it works.
+
+In this guide, we'll be using GraphiQL to run queries and mutations. At each step, you paste the query or mutation into the
+editor pane, and then click the "Play" button to run it. You'll then see the response in the right-hand pane.
+
+![GraphiQL interface](./graphiql.jpeg)
+
+## Shop API
+
+The Shop API is the public-facing API which is used by the storefront application.
+
+Open the GraphiQL Shop API interface at [http://localhost:3000/graphiql/shop](http://localhost:3000/graphiql/shop).
+
+### Fetch a list of products
+
+Let's start with a **query**. Queries are used to fetch data. We will make a query to get a list of products.
+
+<Playground
+    api="shop"
+    document={`
+query GetProducts {
+    products {
+      totalItems
+      items {
+        id
+        name
+      }
+    }
+}
+`}
+/>
+
+Note that the response only includes the properties we asked for in our query (id and name). This is one of the key benefits
+of GraphQL - the client can specify exactly which data it needs, and the server will only return that data!
+
+Let's add a few more properties to the query:
+
+<Playground
+    api="shop"
+    document={`
+query GetProducts {
+    products {
+      totalItems
+      items {
+        id
+        name
+        slug
+        description
+        featuredAsset {
+          id
+          preview
+        }
+      }
+    }
+}
+`}
+/>
+
+You should see that the response now includes the `slug`, `description` and `featuredAsset` properties. Note that the
+`featuredAsset` property is itself an object, and we can specify which properties of that object we want to include in the
+response. This is another benefit of GraphQL - you can "drill down" into the data and specify exactly which properties you
+want to include.
+
+Now let's add some arguments to the query. Some queries (and most mutations) can accept argument, which you put in parentheses
+after the query name. For example, let's fetch the first 5 products:
+
+<Playground
+    api="shop"
+    document={`
+query GetProducts {
+    products(options: { take: 5 }) {
+      totalItems
+      items {
+        id
+        name
+      }
+    }
+}
+`}
+/>
+
+On running this query, you should see just the first 5 results being returned.
+
+Let's add a more complex argument: this time we'll filter for only those products which contain the string "shoe" in the
+name:
+
+<Playground
+    api="shop"
+    document={`
+query GetProducts {
+    products(options: {
+      filter: {
+        name: {
+          contains: "shoe"
+        }
+      }
+    }) {
+      totalItems
+      items {
+        id
+        name
+      }
+    }
+}
+`}
+/>
+
+### Add a product to an order
+
+Next, let's look at a **mutation**. Mutations are used to modify data on the server.
+
+Here's a mutation which adds a product to an order:
+
+<Playground
+    api="shop"
+    document={`
+mutation AddItemToOrder {
+    addItemToOrder(productVariantId: 42, quantity: 1) {
+      ...on Order {
+        id
+        code
+        totalQuantity
+        totalWithTax
+        lines {
+          productVariant {
+            name
+          }
+          quantity
+          linePriceWithTax
+        }
+      }
+      ...on ErrorResult {
+        errorCode
+        message
+      }
+    }
+}
+`}
+/>
+
+This mutation adds a product variant with ID `42` to the order. The response will either be an `Order` object, or an `ErrorResult`.
+We use a special syntax called a **fragment** to specify which properties we want to include in the response. In this case,
+we are saying that if the response is an `Order`, we want to include the `id`, `code`, `totalQuantity`, `totalWithTax` etc., and
+if the response is an `ErrorResult`, we want to include the `errorCode` and `message`.
+
+Running this mutation a second time should show that the quantity of the product in the order has increased by 1.
+
+:::info
+For more information about `ErrorResult` and the handling of errors in Vendure, see the [Error Handling guide](/guides/developer-guide/error-handling).
+:::
+
+## Admin API
+
+The Admin API exposes all the functionality required to manage the store. It is used by the Dashboard, but can also be used
+by integrations and custom scripts.
+
+:::note
+The examples in this section are not interactive, due to security settings on our demo server,
+but you can paste them into your local GraphiQL interface.
+:::
+
+Open the GraphiQL Admin API interface at [http://localhost:3000/graphiql/admin](http://localhost:3000/graphiql/admin).
+
+### Logging in
+
+Most Admin API operations are restricted to authenticated users. So first of all we'll need to log in.
+
+```graphql title="Admin API"
+mutation Login {
+    login(username: "superadmin", password: "superadmin") {
+        ... on CurrentUser {
+            id
+            identifier
+        }
+        ... on ErrorResult {
+            errorCode
+            message
+        }
+    }
+}
+```
+
+### Fetch a product
+
+The Admin API exposes a lot more information about products than you can get from the Shop API:
+
+```graphql title="Admin API"
+query GetProduct {
+  product(id: 42) {
+    // highlight-next-line
+    enabled
+    name
+    variants {
+      id
+      name
+      // highlight-next-line
+      enabled
+      prices {
+        currencyCode
+        price
+      }
+      // highlight-start
+      stockLevels {
+        stockLocationId
+        stockOnHand
+        stockAllocated
+      }
+      // highlight-end
+    }
+  }
+}
+```
+
+:::info
+GraphQL is statically typed and uses a **schema** containing information about all the available queries, mutations and types. In GraphiQL,
+you can explore the schema by clicking the Docs icon (first icon from the top) on the left side of the interface.
+
+![GraphiQL docs explorer](./graphiql-docs.jpeg)
+:::