DEV Community: seyed mojtaba shadab

What is ShaadKit? A Look at My Personal Foundation for Next.js Projects

seyed mojtaba shadab — Wed, 23 Sep 2026 13:28:06 +0000

Where Does the Problem Start?

Imagine you've started a new Next.js project. You're about to build something new and exciting. But before you even write a single line of code for the actual product, you have to get through a mountain of repetitive tasks:

Setting up ESLint with the right config and strict rules
Setting up Stylelint for CSS and CSS Modules
Setting up Storybook for component-driven development
Adding testing with Vitest and Playwright
Setting up i18n for multilingual support from the start
Choosing a UI library and integrating it with Next.js
Setting up the project structure in a way that's ready to scale
Performance tooling like Bundle Analyzer
Various Next.js configurations for optimization
Project conventions from naming to file structure

And this cycle repeats with every new project:

create-next-app
      ↓
  configure
      ↓
fix conventions
      ↓
 add tooling
      ↓
 add testing
      ↓
add UI infrastructure
      ↓
finally start building

Regardless of the fact that this is a repetitive process for every project, it's honestly extremely exhausting (I get really tired of it!)

One of the best solutions is to use ready-made templates or boilerplates. Given that my main focus is on Next.js, the following can be mentioned as examples:

Given the variety of repos, I could probably come up with 50 more examples! But I had a bigger problem.

I Don't Want a Template with Too Many Features

I love it when a project has many capabilities. For example, Next.js handles server components, optimizes images, creates routing, manages backend APIs, and so on. But this is not a good idea at all for ready-made templates!

The reason is obvious. Every technology or feature means making the learning curve steeper. And if a template has too many capabilities, its learning cost increases, while the whole point of using a template is to get started quickly! A developer might even be forced to learn something they've never worked with before or have no interest in using, but they're stuck with it.

I was looking for something where the capabilities would be plentiful enough, but I wouldn't be obligated to use them. I just wanted to use what I actually needed right now! I believe everything should be just enough — neither more nor less... That's why I created ShaadKit.

I'm Happy I Built ShaadKit

For a long time, I was looking for a project that was neither as simple as create-next-app nor like some boilerplates that pack in more than 50 technologies. I wanted to build an MVP very quickly, so I would use technologies that prioritized speed over quality (though quality is also very important to me).

Now, with ShaadKit, I can set up a scalable frontend foundation in just a few clicks!

ShaadKit uses the following technologies:

⚡ Bun as the Package Manager — ultra-fast installation and execution
🧩 Mantine v9 — powerful and accessible components
🌍 next-intl — ready for internationalization from the start
📖 Storybook 10 — component-driven development with MCP and A11y
🧪 Vitest + Playwright — fast and reliable tests
🎨 Stylelint + ESLint (Antfu Config) — top-tier code quality
🔍 Bundle Analyzer — bundle analysis and optimization
⚛️ React 19 + React Compiler — the latest React with automatic optimization

But you might say this contradicts what I said a few paragraphs ago: "Every technology or feature means making the learning curve steeper. And if a template has too many capabilities..." However, my approach to this project is a bit different.

As I explained in the What is the philosophy of this stack? section, I didn't have complex technologies in mind for using ShaadKit, and there's no obligation to use the current technologies. You can even skip Mantine (which is the project's main foundation), but I have good reasons for choosing my technologies.

You don't necessarily have to use ShaadKit for large projects. Sometimes you need to create a simple table, or validate an idea very quickly. Mantine was chosen because it was perfectly suited for such an approach.

It Has a Simple Configuration That Is Just Creative and Powerful Enough

This is something I personally find very appealing. I wanted it so that if a developer doesn't like my coding style, they'd still admit that I chose a forward-thinking foundation for the project.

This is appealing to all businesses and employers.

ShaadKit doesn't have any complex configuration. Everything is simple and minimal, but based on the experience I'd gained, I tried to address some of the blind spots that existed.

Extending the configuration is very easy, and even beginner developers can do it!

I didn't add any library that I didn't find useful. As a result, ShaadKit's core is lightweight.

I Care a Lot About Code Quality

It's very important to me that the code I write always meets the necessary standards. Naturally, for this I had to use tools like ESLint or Oxlint.

I consider Oxlint a very appealing choice, but I chose ESLint because it has more capabilities.

I also added Storybook because developing a component in Storybook is faster than in Next.js! This is possible thanks to Vite. When I first got to know Storybook, it honestly became very hard for me to walk away from it.

I Chose the Best Package Manager (In My Opinion)

I've used both npm and pnpm! Aside from being the most stable, npm doesn't have any defensible feature, but pnpm is a milestone for the world of package managers.

However, on Windows (which has no shortage of developers), pnpm usually performs much slower than it claims, due to the nature of symlinks.

I decided to use Bun as the package manager so I could get both pnpm's speed and npm's stability. If you want to use the same symlink capability, you can enable it in Bun.

I Don't Use Next-intl Just for Internationalization!

Of course, the main reason Next-intl was created is to solve internationalization problems in Next.js, but I look at it from a different angle!

The thing is, maybe the site being developed is monolingual, and there are no plans to add more languages in the near future.

But there's another problem that Next-intl can solve: "managing static text." You've surely run into the issue where, to change a single word on the site, you have to go into several files across different parts of the project and edit them. With Next-intl, all the words are managed in one place with the utmost simplicity.

Integrating Next.js and Next-intl with Mantine

This is also mentioned in Mantine's own documentation. Mantine internally maintains two components, Image and Anchor (which is similar to Link in Next.js).

But the problem is that, under normal circumstances, using these two components means losing the power of Next.js!

In ShaadKit's configuration, from the very start, the Image component (from Next.js) has been merged with the Image component (from Mantine).

Also, for internationalization and Next.js optimization, the Anchor component has been merged with the Link component (exported from Next-intl, which itself extends Next.js).

Just Try It Once

As I said, you can set up ShaadKit very quickly:

Make sure you have Bun installed, and using Node.js version 24 is highly recommended

# Clone the project
git clone https://github.com/shaadcode/shaadkit.git
cd shaadkit

# Install dependencies with Bun
bun install

# Run the development server
bun dev

Who Should Use ShaadKit?

ShaadKit is useful for most projects, but there are always some considerations:

Next.js developers
SaaS projects
MVPs that are likely to grow
Production projects
Multilingual projects
Projects where testing and component development matter

Contribute, Give Feedback, Support

Contributing to ShaadKit is easy. You can report a bug, offer your suggestion, or share your criticism:

If ShaadKit managed to solve a problem for you, I'd be very happy if you gave the repo a star (⭐).

Introducing ICU Studio - Fast and lightweight IDE for ICU messages

seyed mojtaba shadab — Wed, 09 Sep 2026 20:53:39 +0000

As a front-end developer, I often encounter projects that require internationalization (i18n). Making a website multilingual with plain text messages is quite challenging and doesn't offer a great development experience. That's why I decided to use ICU messages.

It's worth noting that using ICU messages directly doesn't make sense—you always need a parser to process them.

Typically, ICU messages are stored inside JSON files so they can be easily used across different projects. However, there's a major issue: editors like VS Code cannot recognize the structure of ICU messages or highlight the different parts of a message (which is natural, since they weren't built for this purpose).

For example, in the image below, it's quite difficult to tell that the argument is actually an ICU variable:

And of course it gets harder if the message gets a bit more complicated (although in real scenarios this is also a simple message):

As I mentioned earlier, this isn't really a problem—it's the normal behavior of editors or IDEs. Because from our perspective, this is an ICU message, but from the editor's perspective, it's just a string and the value of a message key.

So creating or editing ICU messages (at least for me) became a tedious task.

I looked for a tool, but I couldn't find what I wanted!

I was really surprised that this internationalization standard doesn't have a sufficiently good tool to manage it.

Most web developers use VS Code, and there are several extensions that directly or indirectly help with creating or editing ICU messages—but they simply weren't enough. Because even though VS Code is powerful, it can be limiting for development.

Also, I couldn't find any standalone software that I could install on my operating system and comfortably manage ICU messages without any dependencies.

These were the reasons that led me to create ICU Studio...

A lightweight but powerful editor

I decided to use my React development skills to create a desktop application that would solve my problems in this area.

But there were some points I had to consider. For example, my editor had to be fast and very lightweight so it wouldn't slow down development. React is fast enough, but when combined with Electron, it can sometimes become slow—and that's due to Electron's nature, not React itself. Also, it should consume less memory when idle.

Tauri was the tool that helped me build ICU Studio. The result was a very lightweight and optimized application that launches in less than 2 seconds.

But speed wasn't the only thing that mattered to me. I wanted to read ICU messages faster, edit them faster, test different variations, and more...

ICU Studio Features

At the time I'm publishing this article, this editor is in its MVP stage, but it still has enough features that truly solved my problem as a user.

Dedicated Syntax Highlighting

Naturally, the first thing I needed was to understand the structure of my message. Parsing the message and highlighting it made it possible to grasp the overall structure of any message within the first moments of encountering it.

Formatting

In addition to highlighting, formatting the message was another important and fundamental feature of this editor—it increased the readability of messages many times over.

Copy with Different Output Formats

One problem I personally faced in my projects was that sometimes I needed to use the message inside components, and other times inside JSON files. Now ICU Studio can copy the same message in the following four ways:

// simple or pretty copy:
{variable,select,
    option1{text}
    option2{text}
    other{text}
}

// one line copy
{variable,select,option1{text} option2{text} other{text}}

// json property copy
"": "{variable,select,option1{text} option2{text} other{text}}",

// function copy
t('', { variable })

Ready-to-Use Snippets

Up to this point, I had only improved readability. But the problem that still remained was creating an ICU message in the shortest possible time. For example, creating a plural message still took time! Snippets allowed me to generate the entire structure with just one click:

Simple Statistics for Variable Count

When messages become complex, it's helpful to know what types of variables exist and how many of each there are:

Testing Variables Inside the Message

This is a feature I truly enjoy. With a simple user interface, you can quickly test your message, examine different outputs, and have a real-time preview:

As you can see in the image, details of each variable are also displayed, which can be very useful in complex messages.

Message Validation

It's completely normal that human errors can cause the message structure to be incorrect, leading to errors in the project. In ICU Studio, if you encounter an error, you can see the exact reason for it:

Variable Actions

By right-clicking on any variable in your message, you can perform three actions: Delete, Copy, and Cut. All actions are applied only to the specific variable you clicked on:

Undo/Redo

The simplest and one of the most frequently used features that I've found invaluable in ICU Studio. You can comfortably work on complex messages because your change history is never lost, and you can always go back to previous versions.

Smart JSON Property Insertion

In VS Code (when you haven't selected any text), pressing Ctrl+C copies the entire line. Now, if you copy a message with its JSON property, smart insertion allows you to extract just the message value. This is especially useful when your message is long and selecting it with the mouse might take time:

How to Use It?

From download to usage, it takes less than 2 minutes:

Go to the GitHub Releases page
Download and install the appropriate version for your operating system
That's it!

The Future of ICU Studio

Approximately 80% of the major features for ICU Studio have not been built yet. This is a deliberate decision because I want to gather feedback from users and steer the project based on actual needs—not just what I personally want. So there are definitely bigger features waiting for ICU Studio in the future.

Your Support Means a Lot...

This project started as a personal endeavor, but I decided to release it as open source. If this project manages to solve a problem for you, I would be very happy if you could:

⭐ Give the project a star on GitHub
🐛 Report any issues you encounter
💡 Share your feature requests with me
🤝 Contribute to making the project even better

Exploring customLogger: Smart, Customizable Logging in Payload CMS

seyed mojtaba shadab — Tue, 27 May 2025 05:51:03 +0000

🧾 Brief Introduction to Payload CMS

Payload CMS is a Headless content management system based on Node.js and TypeScript, designed for developers. Unlike many traditional CMSs that come with pre-built UIs or themes, Payload focuses on providing a developer-centric, API-driven, and customizable experience.

🎯 Key Features of Payload:

TypeScript-first structure: All structures, data models, and configurations are defined with the powerful TypeScript type system.
Modern admin interface: Automatically generates a complete content management UI from your schema.
Built-in security and authentication: It has a built-in, extensible authentication and access control system.
Hooks and Plugins Support: You can control the behavior of the system precisely using hooks and plugins.

Payload allows developers to create a highly customizable, secure, and extensible content management system without being limited to predefined structures. That is why it is a popular choice for complex, custom, and modern projects.

🔍 What is the `payload-auditor` plugin?

The payload-auditor plugin is a powerful plugin for Payload CMS that allows for precise audit of operations performed on collections. The plugin automatically records all changes such as create, update, and delete data and stores them in a structured log format.

✨ The main goal of this plugin:

Provide a transparent and reliable logging system for monitoring user behavior and reviewing database-level change history.

⚙️ Key features:

Automatic logging of operations on collections
Support for defining custom logger for custom logging
Support for all CMS payload hooks
Modular design with extensibility for complex projects

Using this plugin, developers and system administrators can easily understand who, when, and what changes were made to the system; a vital feature for projects where security, transparency, and audit trails are of high importance. To learn more about this plugin, you can read the article Tracking and Security in Payload CMS with the Payload-Auditor Plugin.

📚 The importance of custom logging in content management systems (CMS)

In content management systems, especially in enterprise or sensitive projects, accurate tracking of user activities and data changes plays a very important role. While basic logging can capture general information about operations, custom logging allows for accurate, targeted, and analyzable information to be stored for the specific needs of each project.

Why do we need custom logging?

1. 🎯 Customization

Projects are different; one project may need to record user IP, another may want to store user roles or geographic information. Custom logging allows for critical information tailored to the project scenario to be recorded.

2. 🕵️‍♀️ Transparency and Audit Trail

For systems that require user behavior to be investigated or security issues to be addressed, the complete change trail (who changed what, when, and how) must be clearly visible. This transparency cannot be achieved without accurate and customized logging.

3. 🔐 Security and Accountability

In many projects, especially in areas such as finance, medicine or government, accurate recording of activities plays an important role in data security and user accountability. Custom logs can also be used as legal evidence.

4. 📊 Analytics and Intelligence

With rich and structured logs, you can analyze user behavior, identify process weaknesses and ultimately make more informed decisions to improve system performance.

Logging is not just a monitoring tool; it is an integral part of security, optimization and professional management of content systems. By providing the ability to record custom logs, you can have much more control and insight into what is happening in the system.

🔧 What is `customLogger`?

In the payload-auditor plugin, the customLogger feature allows developers to fully customize logging behavior at the hook level. This feature is designed for projects that need to generate or modify log content in a specific way depending on different conditions, since it is almost impossible to predict the default values for logging in the logs.

🧩 Defining `customLogger` at the Hook Level

customLogger is an optional function that can be specified in the payload-auditor plugin configuration. This function is called when the hook used for each operation is executed and can edit or overwrite the log data before final storage.

customLogger?: (
  args: Parameters<AllCollectionHooks['afterChange']>[0],
  fields: Omit<AuditorLog, 'hook'>,
) => Omit<AuditorLog, 'hook'> | Promise<Omit<AuditorLog, 'hook'>>

In this function:

args: Contains information about the hook for the same document and can have values like req, operation, doc, etc.
fields: Contains the default log structure without the hook field (because the principle of which hook created this log should not change).
The output of the function should be a final version of AuditorLog (except for the hook added by the plugin).

🔀 Multi-level `customLoggers`

In payload-auditor, we have considered four levels of the customLogger function to increase flexibility.

🔢 `customLogger` definition levels (in order of execution priority):

1. 🥇 Operation-Level

At this level, a dedicated customLogger can be defined for each specific operation (create, update, delete). This level has the highest execution priority and if it exists, no other levels will be executed.

create: {
  customLogger: (args, fields) => {
    return { ...fields, user: null }
  },
  enabled: true,
}

📌 Applies only to that specific operation
✅ Has the highest priority

2. 🥈 Hook-Level

If customLogger is not defined for a specific operation, the system looks for customLogger at the hook level, such as afterChange.

customLogger: (args, fields) => {
  return { ...fields, user: null }
}

📌 Only for specific hook (e.g. afterChange)
❌ Not executed if customLogger is defined as an operation level
✅ Only works on active operations

3. 🥉 All Hooks Level (Hooks-Level)

At this level, customLogger is applied to all hooks and operations, if none of the previous two levels exist.

customLogger: (args, fields) => {
  return { ...fields, type: 'error' }
}

📌 Only runs if there is no logger at the hook and operation level
✅ Only works on active operations
❌ Cannot be defined for a specific hook – covers the entire hook system

4. 🏁 Global-Level

If no customLogger is defined at the operation, hook or all hooks level, then the global customLogger is run. This level works for all collections.

customLogger: (args, fields) => {
  return { ...fields, userAgent: 'custom user agent' }
}

📌 Last level of fallback in execution priority
✅ Works only on active operations

🔁 Execution hierarchy summary:

[Highest priority] Operation → Hook → All hooks → Global [Lowest priority]

The more detailed the definition level, the higher the execution priority. This hierarchy provides great flexibility for precise, customized, and targeted logging.

🧬 `customLogger` structure

The customLogger function is the heart of the custom logging mechanism in the payload-auditor plugin. This function allows you to edit or generate log fields before final logging. To do this, the function takes two inputs and must return a specific output.

🛠 Function Inputs

The customLogger function has two main inputs:

1. `args`: All hook arguments

This argument contains complete information about the current hook and the operation that was executed. Typically contains values like:

req: HTTP request object
operation: Operation type (create, update, delete)
doc: Final document after modification
previousDoc: Previous document (in update and delete operations)
Other information depending on the hook type

2. `fields`: Initial log structure (Log Fields)

This object contains the default log data generated by the plugin, without fields hook. You can override, modify, or add fields to this object.

📍Note: If you want to add a new field, you must define that field for the plugin root collection using configureRootCollection

📤 Expected Output

The customLogger function should return an object that has the following structure:

Omit<AuditorLog, 'hook'>

That is, it must include all the fields required for logging, except hook which is automatically added by the plugin.

📌 Simple example:

(args, fields) => {
return {
...fields,
user: null,
ip: args.req?.ip || 'unknown',
}
}

⏳ Support for async operations

The customLogger function can also operate asynchronously (*****async* ) . That is, you can use async functions such as accessing a database, reading from external APIs or long-running processes and return the final value with await.

📌 Example with Promise:

async (args, fields) => {
const geoInfo = await getGeoInfo(args.req?.ip)
return {
...fields,
location: geoInfo.city,
}
}

🔄 If the function output is of type Promise, the plugin will automatically resolve it.

This flexibility in the customLogger structure allows you to generate the structure you want for any scenario, from simple logging to the most complex analytics.

📌 Practical examples

In this section, we will examine two common examples of customLogger usage; one simple and the other with async operations. Each example is analyzed line by line to make the practical concepts clear.

1. 🧼 Changing the user value to `null`

customLogger: (args, fields) => {
return { ...fields, user: null };
}

🧩 Line-by-line analysis

customLogger: is a synchronous function that takes two parameters:
args: information about the operation, such as request, document, etc.
fields: raw log data before final processing.
...fields: first we keep all the initial fields of the log.
user: null: then we manually set the value of user to null.

🎯 Real-world uses of this change

Removal of sensitive information: In some scenarios you may not want to record user IDs or information (for example, in anonymous forms).
Anonymization of logs for privacy or in test environments.
Automated processes where no human user is involved and user is irrelevant.

2. 🌐 Adding custom information (e.g. IP)

📍Note: If you want to add a new field, you must define that field for the plugin root collection using configureRootCollection

customLogger: async (args, fields) => {
const ip = await getIPFromRequest(args.req);
return { ...fields, meta: { ...fields.meta, ip } };
}

🧩 Line-by-line analysis

The function is async because it uses the await helper function.
getIPFromRequest(args.req): A hypothetical function to extract the IP from the request.
...fields: Preserve the original data.
meta: { ...fields.meta, ip }: Add the IP to the log metadata section, without removing the previous metadata.

🧰 Introducing the helper function

The getIPFromRequest function can be defined simply as:

function getIPFromRequest(req?: PayloadRequest): string {
return req?.ip || req?.headers['x-forwarded-for']?.toString() || 'unknown';
}

This function first gets the IP from req.ip, otherwise it uses proxy headers.

🎯 Real-world applications

Security analysis: Detect suspicious situations by examining IP.
Recording user behavior based on geographic location.
Monitoring system load from specific regions or specific users.

⚠️ Critical points when using `customLogger`

To use customLogger correctly and effectively in the payload-auditor plugin, it is crucial to be familiar with some limitations and prioritization behaviors. In this section, we will review the most important critical points:

🔄 1. Prioritization when using customLogger

If you have defined customLogger at different levels (for example, both at the operation level and at the hook or global level), the plugin will always use the closest definition. The order of precedence is as follows:

customLogger at the operation-level For example:

create: {
customLogger: ...
}

✅ Highest priority – will only be executed for that specific operation.

customLogger at hook level For example:

afterChange: {
customLogger: ...
}

✅ Runs only if the corresponding operation does not have a dedicated customLogger.

customLogger at the global hooks level For example:

hooks: {
customLogger: ...
}

✅ Runs if neither operation-level nor hook-level customLogger exists.

customLogger at global level (for all collections) For example:

auditor: {
customLogger: ...
}

✅ Finally, the final fallback; runs only if no other level has a customLogger.

🧩 2. Differences with `customLogger` at hook level

There are important differences between customLogger at hook level (e.g. afterChange) and operation level:

Feature	customLogger (operation)	customLogger (hook-level)
Dependent on operation type	For any operation you have defined	Yes, but only when not defined
Scope of effect	A specific operation	All operations related to that hook
Execution priority	Higher	Lower than operation level

⚠️ It is important not to confuse these two levels, as you might think your customLogger is running, but because there is a more precise version at a lower level, it is not called at all.

✅ Best Practices

To make your logging system both fast and secure, it is very important to follow a few key principles in the design and implementation of customLogger. In this section, we will discuss recommendations that will both improve the developer experience and make the system easier to maintain:

🧼 1. Keep your log structure simple

Minimalism in logging helps reduce data volume and storage costs.
Avoid adding unnecessary or nested fields.
Always design logs for fast processing in analytics systems (like ELK, Datadog, or Logstash).

✅ Good example:

return {
...fields,
action: 'create',
user: user.id,
};

❌ Bad example:

return {
...fields,
debugDump: req.body,
requestHeaders: req.headers,
timestamp: new Date(),
callStack: new Error().stack,
};

🔐 2. Avoid storing sensitive data (unless encrypted)

📍Note: The plugin itself may store email in raw form in the logs. It is the developer's responsibility to use encryption to store sensitive data

Avoid storing private user data such as email, IP, or phone number in raw form.
If you need to store this data, use encryption or hashing.

✅ Suggested example:

return {
...fields,
meta: {
emailHash: sha256(user.email),
},
};

🌐 3. Use async for external data

If you need to get data from external sources (such as IP location, browser information, or external validations), customLogger fully supports async functions.

Example: Adding user location from IP

customLogger: async (args, fields) => {
const location = await getGeoLocation(args.req?.ip);
return {
...fields,
meta: {
...fields.meta,
location,
},
};
}

📌 Note: If you use external resources:

Pay attention to API latency.
Consider caching or rate-limiting.
Use appropriate timeouts so that the entire log process does not break.

🎯 Other recommendations

Use collections for testing customLogger whose changes are less critical.
Do not use customLogger to modify the original data (it is only for creating logs).
If you need a different customLogger based on the user type, you can put a condition in it:

if (args.req?.user?.role === 'admin') {
return { ...fields, severity: 'high' };
}

📍 Conclusion

The customLogger feature in the payload-auditor plugin is a very powerful tool for customizing the logging process in Payload CMS-based projects. This feature allows you to precisely and with full control, tailor the content of the logs to your project's security, analytical, and operational needs.

🧩 Summary of features

High flexibility at four levels: operation level, hook, hooks-level and global
Ability to process synchronously and asynchronously (async) in log generation
Support for external data such as IP, geolocation or user role
Ability to filter, modify, or remove sensitive information before saving

🎯 More accurate tracking of system changes

By using customLogger wisely, you can:

Record and analyze specific changes based on user context
Generate targeted and actionable logs that are valuable for monitoring and security tools
Make the debugging process faster and more accurate for the development team

💡 Suggestions for developers

Use customLogger to build a reliable logging infrastructure alongside other observability tools like Sentry Or use Grafana.
For projects with high security requirements, be sure to encrypt sensitive data in logs.
Use async loggers to balance system performance with log richness.

Ultimately, customLogger is not just an optional feature, but can be a key part of your audit and security strategy. If used correctly, it can be the difference between a purely decorative log and a real analysis and response tool.

🔗 Link to the main plugin documentation

Official documentation payload-auditor Includes a full explanation of options, log structure, logging levels, and practical examples.

💻 GitHub Repository Link

GitHub Repository: 👉 https://github.com/shaadcode/payload-auditor

In this repo you can:

View and install the latest version of the plugin
Track Issues and Feature Requests
Contribute to the plugin development

🤝 Appreciation and Contribution

If you found this plugin useful or this article helped you understand it better, please support me by giving the payload-auditor repo a ⭐️. This motivates me to develop more open source tools.

🙏 Thank you for your support!

Tracking and Security in Payload CMS with the Payload-Auditor Plugin

seyed mojtaba shadab — Sat, 24 May 2025 05:32:37 +0000

Before we get into the main topic of the article, let's first learn about Payload CMS.

A Brief Introduction to Payload CMS

Payload CMS is a modern, fully JavaScript-based, headless content management system. Unlike many traditional CMSs, Payload has a strong focus on customization, high performance, and a developer-centric experience.

Instead of using pre-built panels, it allows you to fully define the structure and behavior of your admin panel through code. Some of its notable features include:

Full support for TypeScript
Advanced system for defining collections and fields
Ability to add hooks and detailed access control
Headless design for use in separate Frontend projects (React, Next.js, Vue, etc.)
And strong support for authentication, file upload, and REST and GraphQL APIs

Overall, Payload CMS is a powerful option for developers who want full control over the structure and functionality of their CMS — without having to deal with the limitations of traditional platforms.

Why do we need logging and tracing in Payload?

In the world of modern software, especially in projects built with headless CMSs like Payload CMS, the issue of security, transparency, and user behavior analysis is of utmost importance.

As the scale of the project grows and the number of users or administrators increases, knowing who did what, when, and where is no longer an optional feature — it is a vital need.

Here are some reasons why logging and tracing is necessary:

🧑‍💻 Track user actions: Who changed the information? When was a file deleted? Did someone log in with the wrong access?
🛡️ Increase security: Recording suspicious or sensitive events (such as changes to user information or suspicious logins) is the first line of defense against attacks.
🧾 Organizational Transparency: In multi-person teams, knowing the history of actions prevents repetitive errors and creates order in team processes.
🧪 Debugging and analyzing system behavior: Having a history of operations is very helpful when developing or investigating problems.

Payload Auditor Plugin: Answering Your Monitoring and Security Needs

This is where the Payload Auditor plugin comes in. It is designed to work seamlessly with Payload CMS, allowing for detailed logging of operations, event tracking, and greater control over backend security.

Not only does the plugin allow you to specify which collections to track, but you can even fine-tune the type of operation (create, update, delete) per hook. Simply put, you have complete control over what gets logged — without any added overhead or unnecessary complexity.

I’ll give you a more complete explanation later.

Why Payload Auditor?

Common Problems in Payload Projects Without a Logging System

In many projects built with Payload CMS, developers focus primarily on data structure, admin panel design, and API interaction — but an important part that is often overlooked is the logging and event monitoring system.

Here are some common problems that arise in the absence of a proper logging system:

🔍 Lack of Clear Change View
In projects with multiple content managers or developers, it is often unclear who made what changes and when. This can lead to confusion, repeated errors, or even damage to important data.

🛠️ Difficult Debugging
In the event of a problem, the lack of detailed reporting of the operations performed causes the development team to spend a lot of time searching through data or code to understand what happened.

🛡️ High Security Risks
When no traces of sensitive operations (such as updating user information or deleting data) remain, it becomes very difficult to identify suspicious actions or possible abuses.

📉 Lack of internal documentation of system performance
In organizational or team projects, automated documentation of user and system behavior plays a vital role in analyzing and improving processes. Otherwise, this task is either completely forgotten or performed manually and incompletely.

⏸️ Lack of tracking and targeted stopping of operations
Without a monitoring system, it is not possible to centrally specify whether logging should be stopped in a specific section or only certain operations (such as creation or deletion) should be logged.

Payload Auditor fills these gaps — as a simple, flexible, and powerful tool for:

Tracking all important activities
Accurately recording the history of operations
Controlling access to logs
and increasing the overall security of your project

Benefits of Using the Payload Auditor Plugin

Using the Payload Auditor plugin allows developers to make their projects more professional, secure, and more analyzable. Here are the most important benefits of this tool:

✅ Full Activity Tracking
This plugin allows for accurate recording of operations such as user creation, editing, deletion, and login. You can know who did what, when, and what — something that is practically impossible in systems without logging.

🔐 More security in multi-user environments
In projects where multiple users with different access levels are working, tracking and limiting access to logs plays an important role in preventing abuse or unwanted changes. This plugin allows you to control access to reports and closely monitor activities.

🏢 Suitable for SaaS and Enterprise Projects
In SaaS and Enterprise-level projects, detailed reports, change history, and analytical tools are a must. By providing these features, Payload Auditor helps you build a professional, reliable, and industry-standard product.

⚙️ High customization for specific needs
Through flexible settings, this plugin allows you to track only the collections that are important to you, select the type of operations, and even disable its functionality in certain situations.

📊 Analysis of behavioral and operational data
By recording structured events, you can perform valuable analyses on user behavior, system problems, or usage patterns in the future. This information can be useful in optimizing the user experience or making management decisions.

Install and set up the Payload Auditor plugin

Setting up the payload-auditor plugin is very simple and quick, and it can be added to the Payload CMS project in a few short steps. Here are the basic installation and configuration steps:

🧱 Installing with npm / yarn / pnpm

First, add the plugin to your project using your preferred package manager (although we recommend using pnpm):

npm install payload-auditor

Or if you are using yarn:

yarn add payload-auditor

Or with pnpm:

pnpm add payload-auditor

⚙️ Adding the plugin to the Payload configuration

After installation, simply import and enable the plugin in the Payload configuration file (usually payload.config.ts or payload.config.js).

import { buildConfig } from 'payload/config'
import { auditorPlugin } from 'payload-auditor'

export default buildConfig({
  collections: [
    // ... your collections here
  ],
  plugins: [
    auditorPlugin({
      // plugin settings go here
    }),
  ],
})

🛠️ Basic configuration (simple example)

In this simple example, we will configure only one collection called media for logging. Payload-Auditor uses payload cms hooks for logging operations. In this configuration, only update operations will be logged using the afterChange hook:

auditorPlugin({
  collection: {
    trackCollections: [
      {
        slug: 'media',
        hooks: {
          afterChange: {
            update: {
              enabled: true,
            },
          },
        },
      },
    ],
  },
})

With these simple settings, the plugin starts logging changes to the media collection.

Payload Auditor Plugin Configuration Options

The payload-auditor plugin is designed for high flexibility, allowing you to specify exactly which collections are logged, under what conditions, and with what operations. Here are the most important configuration options:

🕒 `automation`

This option manages automated operations in the logging system. For example, you can specify how many old logs you want to delete. You can even specify which logs are considered old:

      automation: {
        logCleanup: {
          strategy: {
            name: 'manual',
            amount: 66,
            olderThan: '2m',
          },
        },
      },

In the above code, logs that are more than two minutes old are considered old and 66 of them are deleted each time. Please note that this is just an example.

📁 `trackCollections`

In this option, you introduce a list of collections whose activities you want to track. For each collection you can have its own settings. The settings in this section are very flexible, meaning you can enable all Payload hooks for each collection and even specify which operations you want to enable.

trackCollections: [
  {
    slug: 'users',
    hooks: {
      afterChange: {
        update: { enabled: true },
        create: { enabled: true },
      },
    },
  },
]

🎯 Filtering operations inside hooks

The plugin allows you to log only some specific operations (for example, only update or delete).
This way, the logs become more targeted and lightweight.

hooks: {
  afterOperation: {
    delete: { enabled: true },
    create: { enabled: false },
  },
}

📦 Complete example of an advanced configuration

In the following example, two collections (users and posts) are tracked. In the users collection, only the update operation is logged in the afterChange hook. In the posts collection, only the delete is logged in the afterOperation hook. Also, the logs are deleted after 30 days:

auditorPlugin({
      automation: {
        logCleanup: {
          strategy: {
            name: 'manual',
            amount: 150,
            olderThan: '7d',
          },
        },
      },
      collection: {
        trackCollections: [
          {
            slug: 'users',
            hooks: {
              afterChange: {
                update: {
                  enabled: true,
                },
              },
            },
          },
          {
            slug: 'posts',
            hooks: {
              afterOperation: {
                delete: {
                  enabled: true,
                },
              },
            },
          },
        ],
      },
    })

How the Payload Auditor Plugin Works

The payload-auditor plugin uses the very powerful hooks feature of Payload CMS to log and track important operations at the collection level. This approach makes logging non-destructive, modular, and controllable.

🔄 Using hooks for logging

By default, Payload CMS provides a set of hooks for each collection, including:

beforeChange
afterChange
beforeOperation
afterOperation
and all payload cms hooks...

By connecting to these hooks, the payload-auditor plugin intercepts and logs all operations that occur in your project — but only if you have enabled it.

📌 Unlike some other tools, this plugin only logs when you tell it to, so there is no additional overhead to your project.

⚙️ Differences between operations (create, update, delete)

For each hook you can specify exactly which type of operation should be logged. For example:

hooks: {
  beforeValidate: {
    update: { enabled: true },
    create: { enabled: false },
  },
}

In this example:

The update operation is logged in the afterChange hook.
But the create operation is ignored. Of course, it is also ignored if you do not fully define this operation. This feature is mostly for when you want to ignore this operation for now and enable it later.

This level of fine-grained control allows you to tailor the logging system to exactly the needs of your project.

⏸️ Ability to temporarily stop logging for a specific collection

You may want to temporarily stop logging on a collection — for example, to fix a bug or during development. The plugin provides this feature as well. Just set the enabled property value to false or remove the collection from the trackCollections list.

Example:

{
  slug: 'comments',
  enabled: false, // This collection is temporarily untracked.
}

Or remove it altogether so that no hooks are attached to it.

This design is both simple and extensible

Usage Scenarios

The payload-auditor plugin is not just a logging tool; it is a tool for analysis, security, and better management of real projects. Here are some of the most common scenarios where this plugin will be very useful:

🔐 Logging user logins and profile changes

In projects where users can log into the admin panel, accurate tracking of when and how they log in or changes to their profile is very important from a security and support perspective.

By enabling logging on the users collection (assuming that site users are stored in a collection with the slug users), you can:

Identify who logged in and when.
Document changes to email, name, password, or user role.
Track support reports faster.

🔍 Security Issues Investigation and User Behavior Analysis

In many cases, suspicious behavior or security issues can be identified simply by looking at the logs. This plugin allows you to:

Track unusual deletion or editing operations.
Analyze specific user or admin behaviors and identify dangerous patterns.
Generate a detailed report for security or compliance audits (in development).

👥 Use in multi-user projects with different access levels

In projects where several people with different roles work on a CMS, such as:

Content Editors
Support Agents
Admins

Managing changes and answering the question "Who did what?" becomes extremely difficult.
The payload-auditor plugin is essential in such environments:

Accurately logging operations for each role
Preventing unwanted or erroneous changes
Helping to build team discipline and trust in large teams

Best practices for using Payload Auditor

To use the payload-auditor plugin effectively and securely, it is recommended to follow some tips and recommendations. Here are some important ones:

✅ 1. Optimal and targeted configuration

Not all collections need logging. Only select those that contain sensitive data or important operations (such as users, orders, payments).

Recommendation:

Only enable hooks and operations that really need to be tracked.
This will reduce the size of the logs and improve system performance.

🧹 2. Intelligent long-term log retention

If not managed properly, logs can cause database size to increase and performance to decrease over time. Use the automation option to control the lifetime of logs.

Example:

 automation: {
        //  ...
      },

In sensitive projects:
If you need long-term retention, move logs to archive systems or centralized logging tools (like ELK Stack or Logstash). For this, you can use customLogger which is provided at 4 levels: global, hook level, specific hook level and operation level.

🔒 3. Restrict access to logs

Not all users should have access to logs. For added security:

Only root admins or users with specific roles (e.g. Auditor) should be able to view or analyze logs.
Restrict access to log collections using Access Control in Payload.

Simple example:

Accessibility:{
          // Your configuration
        },

🧪 4. Testing and Monitoring in the Development Environment

Before using in the production environment, test the plugin’s performance thoroughly in the development or staging environment. Check:

Are logs recorded accurately?
Are unnecessary operations not logged?
Is system performance not degraded?

Following these practices will make the Payload Auditor plugin one of the pillars of your project’s security and professional maintenance, rather than an additional tool.

Conclusion

The Payload Auditor plugin is a powerful and flexible tool that allows you to accurately and securely track user activities and important changes in your Payload CMS projects. With this plugin, you can:

Increase project security in multi-user environments,
Quickly identify problems and suspicious behavior,
Generate detailed and analytical reports for better project management,
And experience all these features with high customization capabilities and precise log management.

If you are also looking to improve security and transparency in your Payload CMS projects, we recommend that you definitely try this plugin.

Contribute to development

This project is open source and interested developers can help improve and expand it by providing feedback, suggestions, or contributing to its development. To view the source code, complete documentation, and start contributing, visit its official GitHub repository:

Payload Auditor on GitHub

With this tool, take an important step towards increasing the security, control, and monitoring of your Payload CMS projects and experience more sustainable development.

Resources and Links

To learn more and better use the Payload Auditor plugin, as well as learn related concepts, you can refer to the following resources:

If you’re looking to increase security, transparency, and analytics in your Payload CMS projects, try the Payload Auditor plugin today.
We’re eager to hear your feedback, suggestions, and contributions to the development of this tool.
Check out the project on GitHub, give it a ⭐ star, and join us in building a stronger and more secure Payload ecosystem!

DEV Community: seyed mojtaba shadab

What is ShaadKit? A Look at My Personal Foundation for Next.js Projects

Where Does the Problem Start?

I Don't Want a Template with Too Many Features

I'm Happy I Built ShaadKit

It Has a Simple Configuration That Is Just Creative and Powerful Enough

I Care a Lot About Code Quality

I Chose the Best Package Manager (In My Opinion)

I Don't Use Next-intl Just for Internationalization!

Integrating Next.js and Next-intl with Mantine

Just Try It Once

Who Should Use ShaadKit?

Contribute, Give Feedback, Support

Introducing ICU Studio - Fast and lightweight IDE for ICU messages

I looked for a tool, but I couldn't find what I wanted!

A lightweight but powerful editor

ICU Studio Features

Dedicated Syntax Highlighting

Formatting

Copy with Different Output Formats

Ready-to-Use Snippets

Simple Statistics for Variable Count

Testing Variables Inside the Message

Message Validation

Variable Actions

Undo/Redo

Smart JSON Property Insertion

How to Use It?

The Future of ICU Studio

Your Support Means a Lot...

Exploring customLogger: Smart, Customizable Logging in Payload CMS

🧾 Brief Introduction to Payload CMS

🎯 Key Features of Payload:

🔍 What is the payload-auditor plugin?

✨ The main goal of this plugin:

⚙️ Key features:

📚 The importance of custom logging in content management systems (CMS)

Why do we need custom logging?

1. 🎯 Customization

2. 🕵️‍♀️ Transparency and Audit Trail

3. 🔐 Security and Accountability

4. 📊 Analytics and Intelligence

🔧 What is customLogger?

🧩 Defining customLogger at the Hook Level

🔀 Multi-level customLoggers

🔢 customLogger definition levels (in order of execution priority):

1. 🥇 Operation-Level

2. 🥈 Hook-Level

3. 🥉 All Hooks Level (Hooks-Level)

4. 🏁 Global-Level

🔁 Execution hierarchy summary:

🧬 customLogger structure

🛠 Function Inputs

1. args: All hook arguments

2. fields: Initial log structure (Log Fields)

📤 Expected Output

⏳ Support for async operations

📌 Practical examples

1. 🧼 Changing the user value to null

🧩 Line-by-line analysis

🎯 Real-world uses of this change

2. 🌐 Adding custom information (e.g. IP)

🧩 Line-by-line analysis

🧰 Introducing the helper function

🎯 Real-world applications

⚠️ Critical points when using customLogger

🔄 1. Prioritization when using customLogger

🧩 2. Differences with customLogger at hook level

✅ Best Practices

🧼 1. Keep your log structure simple

🔐 2. Avoid storing sensitive data (unless encrypted)

🌐 3. Use async for external data

🎯 Other recommendations

📍 Conclusion

🧩 Summary of features

🎯 More accurate tracking of system changes

💡 Suggestions for developers

🔗 Link to the main plugin documentation

💻 GitHub Repository Link

🤝 Appreciation and Contribution

🔍 What is the `payload-auditor` plugin?

🔧 What is `customLogger`?

🧩 Defining `customLogger` at the Hook Level

🔀 Multi-level `customLoggers`

🔢 `customLogger` definition levels (in order of execution priority):

🧬 `customLogger` structure

1. `args`: All hook arguments

2. `fields`: Initial log structure (Log Fields)

1. 🧼 Changing the user value to `null`

⚠️ Critical points when using `customLogger`

🧩 2. Differences with `customLogger` at hook level

🕒 `automation`

📁 `trackCollections`