Features

• Rich-Text Editor: Built-in Tiptap editor with support for bold, italic, headings, lists, images, and YouTube embeds.
• SEO Ready: Automatic handle (slug) management for clean, searchable URLs.
• Publication Workflow: Support for draft and published statuses.
• Read Metrics: Built-in read_count and read_time calculation/storage.
• Categorization: Support for tags and short descriptions.
• Admin Dashboard: Full CRUD interface for managing posts within the Medusa Admin.

Compatibility

• Medusa v2 (>= 2.4.0)
• PostgreSQL

Installation

1. Install the Plugin

# Using npm
npm install medusa-blog-management

# Using yarn
yarn add medusa-blog-management

2. Install Peer Dependencies (Required for Admin)

The Admin rich-text editor requires Tiptap dependencies to be installed in your main Medusa store:

npm install @tiptap/react @tiptap/starter-kit @tiptap/extension-image @tiptap/extension-youtube

2. Configuration

Add the plugin to your medusa-config.ts. In Medusa v2, you need to register it in both modules (for database functionality) and plugins (for admin UI):

const { defineConfig } = require("@medusajs/framework/utils")

module.exports = defineConfig({
  // ... rest of config
  modules: {
    blog: {
      resolve: "medusa-blog-management",
    },
  },
  plugins: [
    {
      resolve: "medusa-blog-management",
    },
  ],
})

[!IMPORTANT] Admin UI Not Showing? Make sure the plugin is registered in both modules and plugins arrays. The modules entry enables database functionality, while the plugins entry enables the admin UI routes.

After adding the plugin:

1. Rebuild the plugin: cd medusa-blog-management && npm run build
2. Restart your Medusa server
3. Hard refresh your browser (Ctrl+Shift+R or Cmd+Shift+R)

3. Database Migrations

Run the following command to create the blog_post table:

npx medusa db:migrate

Note: Ensure your database environment variables (DB_URL or DB_HOST, DB_NAME, etc.) are set in your Medusa server's .env file.

Using Storefront Helpers

The plugin exports typed helpers for easy integration with your storefront.

import { getBlogList, getBlogPost } from "medusa-blog-management/helpers"

// Fetch list of posts
const { posts, count } = await getBlogList({ 
  take: 10, 
  skip: 0 
}, {
  baseUrl: "https://api.yourstore.com",
  publishableApiKey: "pk_..."
})

// Fetch single post
const { post } = await getBlogPost("post_handle_123", {
  baseUrl: "https://api.yourstore.com",
  publishableApiKey: "pk_..."
})

Metadata Helper (Next.js Example)

import { getBlogMetadata } from "medusa-blog-management/helpers"

export async function generateMetadata({ params }) {
  const { post } = await getBlogPost(params.id)
  return getBlogMetadata(post)
}

API Reference

Store API

List Posts

GET /store/blog-posts

• Supports pagination via skip and take query parameters.

Get Post

GET /store/blog-posts/:id

• Retrieves a specific post and automatically increments its read_count.

Admin API

Full CRUD Support

The plugin provides endpoints for creating, updating, and deleting posts under /admin/blog-posts.

Customization

The rich-text editor component is available for extension if you need to add custom Tiptap extensions.

Production Notes

Important Information

1. Type Safety: This plugin uses TypeScript strict mode and proper type definitions throughout. All API endpoints are fully typed with DTOs.

2. Input Validation: All POST/PUT endpoints use Zod schemas for validation. Invalid requests will return 400 Bad Request with detailed error messages.

3. Error Handling: All API routes include comprehensive error handling with appropriate HTTP status codes:

   • 400 - Validation errors or bad requests
   • 404 - Resource not found
   • 500 - Internal server errors

4. Service Resolution: The service uses proper dependency injection patterns following Medusa v2 best practices. The manager is correctly injected via the container.

5. Database Transactions: The service properly handles database transactions through MedusaService's built-in transaction management.

API Endpoints

Admin API

Create Blog Post

POST /admin/blog-posts
Content-Type: application/json

{
  "title": "My Blog Post",
  "status": "draft", // optional, defaults to "draft"
  "thumbnail": "https://example.com/image.jpg", // optional
  "short_description": "Brief description", // optional
  "read_time": 300, // optional, in seconds
  "tags": ["tag1", "tag2"], // optional
  "body": "<p>Content</p>", // optional
  "created_by": "Author Name", // optional
  "metadata": {} // optional
}

Update Blog Post

POST /admin/blog-posts/:id
Content-Type: application/json

{
  "title": "Updated Title", // all fields optional
  "status": "published",
  ...
}

Get Blog Post

GET /admin/blog-posts/:id

List Blog Posts

GET /admin/blog-posts?skip=0&take=20

Delete Blog Post

DELETE /admin/blog-posts/:id

Store API

List Posts (Public)

GET /store/blog-posts?skip=0&take=10

Get Post (Public, increments read_count)

GET /store/blog-posts/:id

Validation Rules

• title: Required, 1-500 characters
• handle: Auto-generated from title if not provided, must be unique
• status: Must be "draft" or "published"
• thumbnail: Must be a valid URL if provided
• short_description: Max 1000 characters
• read_time: Must be a non-negative integer
• tags: Array of strings
• created_by: Max 255 characters

Troubleshooting

Error: "Cannot read properties of undefined (reading 'fork')"

Cause: This error occurs when the EntityManager is not available in the container. This typically happens when:

• The plugin isn't properly registered in medusa-config.ts
• The plugin wasn't rebuilt after code changes
• The Medusa server wasn't restarted
• The plugin isn't properly installed/linked in your main project

Solution: Follow these steps in order:

1. Verify plugin registration in medusa-config.ts:

const { defineConfig } = require("@medusajs/framework/utils")

module.exports = defineConfig({
  // ... rest of config
  modules: {
    blog: {
      resolve: "medusa-blog-management",
    },
  },
  plugins: [
    {
      resolve: "medusa-blog-management",
    },
  ],
})

2. Rebuild the plugin:

cd medusa-blog-management
npm run build

3. If using local development (yalc or file path), reinstall/link:

# If using yalc
cd medusa-blog-management
yalc push

# Then in your main project
yalc update medusa-blog-management

# Or if using npm/yarn link
cd medusa-blog-management
npm link

# Then in your main project
npm link medusa-blog-management

4. Restart your Medusa server completely (stop and start, don't just reload)

5. Verify database connection - Ensure your database environment variables are set:

# Check your .env file has:
DATABASE_URL=postgresql://...
# or
DB_HOST=...
DB_NAME=...
DB_USER=...
DB_PASSWORD=...

6. Check the build output - Ensure .medusa/server/src/modules/blog/service.js exists:

ls -la medusa-blog-management/.medusa/server/src/modules/blog/

7. Clear node_modules and reinstall (if still not working):

# In your main Medusa project
rm -rf node_modules package-lock.json
npm install

If the error persists, check the Medusa server logs for more details about module initialization.

Error: "Validation failed"

Cause: Request body doesn't match the expected schema.

Solution: Check the validation error response for specific field errors:

{
  "message": "Validation failed",
  "errors": [
    {
      "path": ["title"],
      "message": "Title is required"
    }
  ]
}

Admin UI Not Loading / Blog Section Not Showing

Solution:

1. Verify plugin registration: Ensure the plugin is registered in both modules and plugins arrays in medusa-config.ts:

modules: {
  blog: {
    resolve: "medusa-blog-management",
  },
},
plugins: [
  {
    resolve: "medusa-blog-management",
  },
],

2. Rebuild the plugin:

cd medusa-blog-management
npm run build

3. Restart your Medusa server completely

4. Ensure peer dependencies are installed in your main Medusa project:

npm install @tiptap/react @tiptap/starter-kit @tiptap/extension-image @tiptap/extension-youtube

5. Clear browser cache and hard refresh (Ctrl+Shift+R or Cmd+Shift+R)

6. Check the browser console for any errors

7. Verify the admin export: The plugin should export admin routes. Check that .medusa/server/src/admin/index.js exists after building.

If the Blog section still doesn't appear, check:

• The plugin is installed: npm list medusa-blog-management
• The build output exists: ls -la .medusa/server/src/admin/
• No TypeScript/build errors: npm run build completes successfully

Database Migration Issues

Solution:

1. Ensure database connection is properly configured
2. Run migrations:

npx medusa db:migrate

3. If migrations fail, check the migration file exists at: src/modules/blog/migrations/Migration20260112153000.ts

TypeScript Errors

Solution: The plugin uses TypeScript strict mode. Ensure:

1. Your project's TypeScript version is compatible (>= 5.6.2)
2. All dependencies are properly installed
3. Run npm install to ensure all types are available

Development

Building the Plugin

npm run build

Development Mode

npm run dev

This will watch for changes and rebuild automatically.

Changelog

Version 0.0.7+

• Fixed critical service constructor bug causing manager undefined errors
• Added comprehensive input validation with Zod schemas
• Improved error handling with proper HTTP status codes
• Enhanced type safety throughout the codebase
• Removed all any types and @ts-ignore comments
• Enabled TypeScript strict mode
• Added proper DTOs and type definitions
• Improved API route error handling

License

MIT