chore: reorganize docs apps (#7228)
* reorganize docs apps * add README * fix directory * add condition for old docs
This commit is contained in:
Shahed Nasser
@@ -0,0 +1,88 @@
|
||||
export const metadata = {
|
||||
title: `${pageNumber} Feature Flags`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
In this chapter, you’ll learn about feature flags and how Medusa uses them.
|
||||
|
||||
## What is a Feature Flag?
|
||||
|
||||
A feature flag is a configuration that toggles beta features in Medusa.
|
||||
|
||||
A beta feature may be disabled but is still part of the published `@medusajs/medusa` package. This allows our team to release new features rapidly and continuously without impacting Medusa applications used in production.
|
||||
|
||||
Developers interested in testing a new feature can enable its flag through Medusa’s configurations.
|
||||
|
||||
<Note type="warning">
|
||||
|
||||
Enabling a feature flag isn’t recommended for Medusa applications in a production environment, as it can cause unexpected errors and issues.
|
||||
|
||||
</Note>
|
||||
|
||||
{/* TODO re-add this based on whether we have feature flags (after V2). */}
|
||||
|
||||
{/* ---
|
||||
|
||||
## List of Feature Flags
|
||||
|
||||
Refer to this reference for a full list of feature flags. */}
|
||||
|
||||
---
|
||||
|
||||
## How to Toggle a Feature Flag
|
||||
|
||||
### Option 1: Using an Environment Variable
|
||||
|
||||
A feature flag has an associated environment variable that, if you set it, it toggles the feature flag.
|
||||
|
||||
For example:
|
||||
|
||||
```bash
|
||||
MEDUSA_FF_TAX_INCLUSIVE_PRICING=true
|
||||
```
|
||||
|
||||
### Option 2: Using Medusa Configurations
|
||||
|
||||
A feature flag also has an associated key that can be used to toggle its value in Medusa’s configurations.
|
||||
|
||||
The configuration object exported in `medusa-config.js` has a `featureFlags` property. Its value is an object where each key is the key of a feature flag, and its value is a boolean indicating whether to enable or disable the flag.
|
||||
|
||||
For example:
|
||||
|
||||
```js title="medusa-config.js"
|
||||
module.exports = {
|
||||
featureFlags: {
|
||||
tax_inclusive_pricing: true,
|
||||
},
|
||||
// ...
|
||||
}
|
||||
```
|
||||
|
||||
<Note title="Tip">
|
||||
|
||||
If you’ve set both the environment variable and the feature flag key in the configurations, the environment variable’s value has a higher precedence.
|
||||
|
||||
</Note>
|
||||
|
||||
### Run Migrations
|
||||
|
||||
A feature guarded by a flag may require changes in the database.
|
||||
|
||||
So, after enabling a feature flag, it’s recommended to run migrations in your Medusa application:
|
||||
|
||||
```bash
|
||||
npx medusa migrations run
|
||||
```
|
||||
|
||||
If you disable the feature flag, run the following command to revert migrations:
|
||||
|
||||
```bash
|
||||
npx medusa migrations revert
|
||||
```
|
||||
|
||||
<Note>
|
||||
|
||||
This reverts the last migrations, so if you ran other migrations since you toggled the feature flag, it’ll revert them instead. You can run it multiple times to revert the last migrations.
|
||||
|
||||
</Note>
|
||||
@@ -0,0 +1,148 @@
|
||||
export const metadata = {
|
||||
title: `${pageNumber} Logging`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
In this chapter, you’ll learn how to use Medusa’s logging utility.
|
||||
|
||||
## Logger Class
|
||||
|
||||
Medusa provides a `Logger` class that provides advanced logging functionalities. This includes configuring logging levels or saving logs to a file.
|
||||
|
||||
The Medusa application registers the `Logger` class in the Medusa container and each module's container as `logger`.
|
||||
|
||||
---
|
||||
|
||||
## How to Log a Message
|
||||
|
||||
Resolve the `logger` using the Medusa container to log a message in your resource.
|
||||
|
||||
For example, create the file `src/loaders/log-message.ts` with the following content:
|
||||
|
||||
export const highlights = [
|
||||
["4", "resolve", "Resolve the `Logger` class."],
|
||||
["6", "info", "Log a message of level `info`."]
|
||||
]
|
||||
|
||||
```ts title="src/loaders/log-message.ts" highlights={highlights}
|
||||
import { Logger, MedusaContainer } from "@medusajs/medusa"
|
||||
|
||||
export default async (container: MedusaContainer) => {
|
||||
const logger: Logger = container.resolve("logger")
|
||||
|
||||
logger.info("I'm using the logger!")
|
||||
}
|
||||
```
|
||||
|
||||
This creates a loader that resolves the `logger` from the Medusa container and uses it to log a message.
|
||||
|
||||
### Test the Loader
|
||||
|
||||
To test out the above loader, start the Medusa application:
|
||||
|
||||
```bash npm2yarn
|
||||
npm run dev
|
||||
```
|
||||
|
||||
You’ll see the following message as part of the logged messages:
|
||||
|
||||
```text
|
||||
info: I'm using the logger!
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Log Levels
|
||||
|
||||
The `Logger` class has the following methods:
|
||||
|
||||
- `info`: The message is logged with level `info`.
|
||||
- `warn`: The message is logged with level `warn`.
|
||||
- `error`: The message is logged with level `error`.
|
||||
- `debug`: The message is logged with level `debug`.
|
||||
|
||||
Each of these methods accepts a string parameter to log in the terminal with the associated level.
|
||||
|
||||
---
|
||||
|
||||
## Logging Configurations
|
||||
|
||||
### Log Level
|
||||
|
||||
The available log levels, from lowest to highest levels, are:
|
||||
|
||||
1. `silly` (default, meaning messages of all levels are logged)
|
||||
2. `debug`
|
||||
3. `info`
|
||||
4. `warn`
|
||||
5. `error`
|
||||
|
||||
You can change that by setting the `LOG_LEVEL` environment variable to the minimum level you want to be logged.
|
||||
|
||||
For example:
|
||||
|
||||
```bash
|
||||
LOG_LEVEL=error
|
||||
```
|
||||
|
||||
This logs `error` messages only.
|
||||
|
||||
<Note title="Important">
|
||||
|
||||
The environment variable must be set as a system environment variable and not in `.env`.
|
||||
|
||||
</Note>
|
||||
|
||||
### Save Logs in a File
|
||||
|
||||
Aside from showing the logs in the terminal, you can save the logs in a file by setting the `LOG_FILE` environment variable to the path of the file relative to the Medusa server’s root directory.
|
||||
|
||||
For example:
|
||||
|
||||
```bash
|
||||
LOG_FILE=all.log
|
||||
```
|
||||
|
||||
Your logs are now saved in the `all.log` file at the root of your Medusa application.
|
||||
|
||||
<Note title="Important">
|
||||
|
||||
The environment variable must be set as a system environment variable and not in `.env`.
|
||||
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## Show Log with Progress
|
||||
|
||||
The `Logger` class has an `activity` method used to log a message of level `info`. If the Medusa application is running in a development environment, a spinner starts that can be used to show progress and succeed or fail the progress.
|
||||
|
||||
For example:
|
||||
|
||||
```ts title="src/loaders/log-message.ts"
|
||||
import { Logger, MedusaContainer } from "@medusajs/medusa"
|
||||
|
||||
export default async (container: MedusaContainer) => {
|
||||
const logger = container.resolve<Logger>("logger")
|
||||
|
||||
const activityId = logger.activity("First log message")
|
||||
|
||||
logger.progress(activityId, `Second log message`)
|
||||
|
||||
logger.success(activityId, "Last log message")
|
||||
}
|
||||
|
||||
```
|
||||
|
||||
The `activity` method returns the ID of the started activity. This ID can then be passed to one of the following methods of the `Logger` class:
|
||||
|
||||
- `progress`: Log a message of level `info` that indicates progress within that same activity.
|
||||
- `success`: Log a message of level `info` that indicates that the activity has succeeded. This also ends the associated activity.
|
||||
- `failure`: Log a message of level `error` that indicates that the activity has failed. This also ends the associated activity.
|
||||
|
||||
<Note>
|
||||
|
||||
If you configured the `LOG_LEVEL` environment variable to a level higher than those associated with the above methods, their messages won’t be logged.
|
||||
|
||||
</Note>
|
||||
@@ -0,0 +1,13 @@
|
||||
export const metadata = {
|
||||
title: `${pageNumber} Debugging and Testing`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
In the next chapters, you’ll find some tips when debugging and testing your customizations in the Medusa application.
|
||||
|
||||
By the end of this chapter, you’ll learn:
|
||||
|
||||
- How to use Medusa’s `Logger` utility to log messages.
|
||||
- What tools to use for testing and debugging.
|
||||
- What feature flags are and how to enable them.
|
||||
@@ -0,0 +1,73 @@
|
||||
export const metadata = {
|
||||
title: `${pageNumber} Debugging and Testing Tools`,
|
||||
}
|
||||
|
||||
# {metadata.title}
|
||||
|
||||
In this chapter, you’ll learn about debugging and testing tools you can use.
|
||||
|
||||
<Note title="Tip">
|
||||
|
||||
Since the Medusa server is a Node.js server, you can use any Node.js testing tool you prefer, even if it’s not listed here.
|
||||
|
||||
</Note>
|
||||
|
||||
## Jest
|
||||
|
||||
[Jest](https://jestjs.io/) is a JavaScript testing framework. Your Medusa project is already configured with Jest; you can use it out-of-the-box.
|
||||
|
||||
For example, consider the following service created at `src/modules/hello/service.ts`:
|
||||
|
||||
```ts title="src/modules/hello/service.ts"
|
||||
import { TransactionBaseService } from "@medusajs/medusa"
|
||||
|
||||
class HelloWorldService extends TransactionBaseService {
|
||||
constructor(container) {
|
||||
super(arguments[0])
|
||||
}
|
||||
getMessage(): string {
|
||||
return "Hello, world!"
|
||||
}
|
||||
}
|
||||
|
||||
export default HelloWorldService
|
||||
|
||||
```
|
||||
|
||||
You can write a test for it in the file `src/modules/hello/__tests__/hello-world.ts`:
|
||||
|
||||
```ts title="src/modules/hello/__tests__/hello-world.ts"
|
||||
import HelloWorldService from "../hello-world"
|
||||
|
||||
describe("HelloWorldService", () => {
|
||||
const helloWorldService = new HelloWorldService()
|
||||
|
||||
it("should return hello world message", () => {
|
||||
expect(helloWorldService.getMessage()).toBe("Hello, world!")
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
Then, run the following command in the root of your Medusa project to run the test:
|
||||
|
||||
```bash npm2yarn
|
||||
npm run test
|
||||
```
|
||||
|
||||
This command looks for TypeScript and JavaScript files under any directory named `__tests__` and runs them.
|
||||
|
||||
---
|
||||
|
||||
## IDE Debugging Tools
|
||||
|
||||
Your IDE may provide a debugging tool for Node.js. In that case, you can use that tool to debug your Medusa customizations.
|
||||
|
||||
For example, if you’re using VSCode, refer to [this guide](https://code.visualstudio.com/docs/nodejs/nodejs-debugging) to learn how to configure and use the debugger.
|
||||
|
||||
---
|
||||
|
||||
## Node.js Debugger
|
||||
|
||||
You can also use Node.js’s Debugger API to debug your Medusa customizations.
|
||||
|
||||
Refer to [Node.js’s documentation](https://nodejs.org/docs/latest-v18.x/api/debugger.html) for more details.
|
||||
Reference in New Issue
Block a user