api-ref: custom API reference (#4770)

* initialized next.js project * finished markdown sections * added operation schema component * change page metadata * eslint fixes * fixes related to deployment * added response schema * resolve max stack issue * support for different property types * added support for property types * added loading for components * added more loading * type fixes * added oneOf type * removed console * fix replace with push * refactored everything * use static content for description * fixes and improvements * added code examples section * fix path name * optimizations * fixed tag navigation * add support for admin and store references * general enhancements * optimizations and fixes * fixes and enhancements * added search bar * loading enhancements * added loading * added code blocks * added margin top * add empty response text * fixed oneOf parameters * added path and query parameters * general fixes * added base path env variable * small fix for arrays * enhancements * design enhancements * general enhancements * fix isRequired * added enum values * enhancements * general fixes * general fixes * changed oas generation script * additions to the introduction section * added copy button for code + other enhancements * fix response code block * fix metadata * formatted store introduction * move sidebar logic to Tags component * added test env variables * fix code block bug * added loading animation * added expand param + loading * enhance operation loading * made responsive + improvements * added loading provider * fixed loading * adjustments for small devices * added sidebar label for endpoints * added feedback component * fixed analytics * general fixes * listen to scroll for other headings * added sample env file * update api ref files + support new fields * fix for external docs link * added new sections * fix last item in sidebar not showing * move docs content to www/docs * change redirect url * revert change * resolve build errors * configure rewrites * changed to environment variable url * revert changing environment variable name * add environment variable for API path * fix links * fix tailwind settings * remove vercel file * reconfigured api route * move api page under api * fix page metadata * fix external link in navigation bar * update api spec * updated api specs * fixed google lint error * add max-height on request samples * add padding before loading * fix for one of name * fix undefined types * general fixes * remove response schema example * redesigned navigation bar * redesigned sidebar * fixed up paddings * added feedback component + report issue * fixed up typography, padding, and general styling * redesigned code blocks * optimization * added error timeout * fixes * added indexing with algolia + fixes * fix errors with algolia script * redesign operation sections * fix heading scroll * design fixes * fix padding * fix padding + scroll issues * fix scroll issues * improve scroll performance * fixes for safari * optimization and fixes * fixes to docs + details animation * padding fixes for code block * added tab animation * fixed incorrect link * added selection styling * fix lint errors * redesigned details component * added detailed feedback form * api reference fixes * fix tabs * upgrade + fixes * updated documentation links * optimizations to sidebar items * fix spacing in sidebar item * optimizations and fixes * fix endpoint path styling * remove margin * final fixes * change margin on small devices * generated OAS * fixes for mobile * added feedback modal * optimize dark mode button * fixed color mode useeffect * minimize dom size * use new style system * radius and spacing design system * design fixes * fix eslint errors * added meta files * change cron schedule * fix docusaurus configurations * added operating system to feedback data * change content directory name * fixes to contribution guidelines * revert renaming content * added api-reference to documentation workflow * fixes for search * added dark mode + fixes * oas fixes * handle bugs * added code examples for clients * changed tooltip text * change authentication to card * change page title based on selected section * redesigned mobile navbar * fix icon colors * fix key colors * fix medusa-js installation command * change external regex in algolia * change changeset * fix padding on mobile * fix hydration error * update depedencies
2023-08-15 18:07:54 +03:00
parent 16249ec280
commit 914d773d3a
3270 changed files with 22075 additions and 192064 deletions
@@ -0,0 +1,86 @@
+---
+description: 'Learn how to create a loader in Medusa. A loader can be created in the Medusa backend codebase, in a plugin, or in a module.'
+addHowToData: true
+---
+
+# How to Create a Loader
+
+In this document, you’ll learn how to create a loader in Medusa. A loader can be created in the Medusa backend codebase, in a plugin, or in a module.
+
+## Step 1: Create Loader File
+
+Create a TypeScript or JavaScript file in the `src/loaders` directory that will hold your custom script. There are no restrictions on the name of the file.
+
+For example, create the file `src/loaders/my-loader.ts` that will hold the loader.
+
+---
+
+## Step 2: Define the Loader
+
+The loader file must export a function.
+
+### Parameters of Loaders in Medusa Backend and Plugins
+
+When the loader is defined in the Medusa backend or a plugin, the function receives the following parameters:
+
+1. `container`: the first parameter, which is a `AwilixContainer` object. You can use the container to register custom resources into the dependency container or resolve resources from the dependency container.
+2. `config`: the second parameter, which is an object that holds the loader’s plugin options. If the loader is not created inside a plugin, the config object will be empty.
+
+### Parameters of Loaders in Modules
+
+When the loader is defined in a module, it receives the following parameters:
+
+1. `container`: the first parameter, which is a `AwilixContainer` object. You can use the container to register custom resources into the dependency container or resolve resources from the dependency container.
+2. `logger`: the second parameter, which is a `Logger` object. The logger can be used to log messages in the console.
+3. `config`: the third parameter, which is an object that holds the loader’s module options.
+
+### Example Implementation
+
+For example, this loader function resolves the `ProductService` and logs in the console the count of products in the Medusa backend:
+
+```ts title=src/loaders/my-loader.ts
+import { ProductService } from "@medusajs/medusa"
+import { AwilixContainer } from "awilix"
+
+export default async (
+  container: AwilixContainer,
+  config: Record<string, unknown>
+): Promise<void> => {
+  console.info("Starting loader...")
+  const productService = container.resolve<ProductService>(
+    "productService"
+  )
+  console.info(`Products count: ${
+    await productService.count()
+  }`)
+  console.info("Ending loader...")
+}
+```
+
+---
+
+## Step 3: Run Build Command
+
+In the directory of your project, run the following command to transpile the files from the `src` to the `dist` directory:
+
+```bash npm2yarn
+npm run build
+```
+
+---
+
+## Test it Out
+
+:::note
+
+This section explains how to test out the loader if it’s created in the Medusa backend codebase. If you’re creating your loader in a plugin, you can learn how to test it in the [plugins documentation](../plugins/create.mdx#test-your-plugin). Alternatively, if you’re creating your loader in a module, you can learn how to test it in the [modules documentation](../modules/create.mdx#step-4-test-your-module).
+
+:::
+
+Run the following command to start the Medusa backend:
+
+```bash npm2yarn
+npx medusa develop
+```
+
+Your loader script should run on the Medusa backend startup. If you logged a message in the console, similar to the example above, you should see it in the console.
@@ -0,0 +1,69 @@
+---
+description: "Learn what loaders are in Medusa. A loader is a script that runs when the Medusa backend starts."
+---
+
+import DocCard from '@theme/DocCard';
+import Icons from '@theme/Icon';
+
+# Loaders
+
+In this document, you’ll learn what loaders are in Medusa.
+
+## Overview
+
+A loader is a script that runs when the Medusa backend starts. The Medusa backend uses loaders to initialize the database connection, load plugins, register resources in the dependency container, and more.
+
+Loaders can be created within the Medusa backend codebase, in a plugin, or in a module to perform custom actions when the backend starts. The loader is created in a TypeScript or JavaScript file located in the `src/loaders` directory, then transpiled using the `build` command into the `dist/loaders` directory.
+
+### Loader Examples
+
+For example, the Redis Event Bus module uses a loader to establish a connection with Redis and log a message in the console.
+
+Another example is the Algolia plugin, which uses a loader to update the index settings when the Medusa backend starts based on the plugin’s options.
+
+Loaders can be used to access the dependency container and register custom resources in it.
+
+Loaders can also be used to create [scheduled jobs](../scheduled-jobs/overview.mdx) that run at a specified interval of time. For example:
+
+```ts
+const publishJob = async (container, options) => {
+  const jobSchedulerService = 
+    container.resolve("jobSchedulerService")
+  jobSchedulerService.create(
+    "publish-products", 
+    {}, 
+    "0 0 * * *", 
+    async () => {
+      // job to execute
+      const productService = container.resolve("productService")
+      const draftProducts = await productService.list({
+        status: "draft",
+      })
+
+      for (const product of draftProducts) {
+        await productService.update(product.id, {
+          status: "published",
+        })
+      }
+    }
+  )
+}
+
+export default publishJob
+```
+
+---
+
+## Custom Development
+
+Developers can create a loader with the desired functionality directly within the Medusa Core, in a plugin, or in a module.
+
+<DocCard item={{
+  type: 'link',
+  href: '/development/loaders/create',
+  label: 'Create a Loader',
+  customProps: {
+    icon: Icons['academic-cap-solid'],
+    description: 'Learn how to create a loader.'
+  }
+}} />