[RFC] Optimize error printing and suggestions

[chenjiahan]

1. Summary

We want to optimize error printing and add more suggestions to the error logs in Modern.js. This will make it easier for developers to address and solve problems.

2. Basic example

A good error log has four parts:

• Error message
• Error stack
• A suggestion about the error
• An example of how to fix the error

A good example from Vitest:

3. Motivation

• Provide a better developer experience for Modern.js users.
• Reduce our maintenance cost.

4. Detailed design

Error messages and stack

There are already many error messages in the Modern.js framework, some of which are thrown by low-level tools, such as webpack, Rspack and babel.

We want to:

• Improve the content of these messages.
• Format the messages from low-level tools if they are not good enough.
• Display the complete error stacks instead of stripping them.

And we can follow some principles to improve the quality of the message:

• Understand the error: before writing the message, we should know why the error happened and how it can be fixed.
• English by default: provide English messages by default, and some frequent errors can use the i18n module to provide a Chinese version.
• Keep it short and simple: error messages should be concise to help developers fix errors quickly.
  • An example:

// Bad
Can’t create 'Engineering' because a team with that name already exists. Specify a different name.

// Good
'Engineering' already exists. Try another team name.

Suggestion and example

Currently, Modern.js does not provide enough suggestions and examples in the error logs, and we should add them to help users quickly solve some common problems.

For example, we have already written many FAQs for Modern.js Builder, and we can integrate those FAQs into the error logs, so that users do not have to open the document and search for the solutions.

5. Some examples

Here are some examples of changes that have been made:

Add suggestion and example (#4288)

Before

After

Use the standard logger module (#3262)

Before

After

Display the complete error stack (#4135)

Before

After

Provide i18n error messages (#4151)

Before (Only Chinese)

After

• English:

• Chinese:

6. Refs

• https://stackoverflow.design/content/examples/error-messages/

[targeral]

Is it possible that for some errors we can automatically modify the configuration to fix them?

For example for an error like this:

We can modify the project's modern.config:

// Some notes explaining the `patchConfig`
export const patchConfig = {
    source: {
        include: ['foo'],
    },
};

export default defineConfig({
   source: {
      include: [/*...*/],
   }
});

The patchConfig is merged with the default exported configuration.

[chenjiahan]

Modifying the TS code is a risky operation. The user code contains a lot of dynamic usage, and we can only handle a limited number of scenarios.

That's why the modern new command doesn't modify the config file, but prints logs to allow users to modify it manually.

[targeral]

I realize that user code can be complex, so simply adding the patchConfig object to the config file. However, modifying files, especially ts files, does present some difficulty, so maybe try using ts-morph to modify the file.

To put it another way, it might be possible if we generate an additional config file modern.patch.config.(j|ts).

modern.patch.config

export const patchConfig = {
    source: {
        include: ['foo'],
    },
};

On each build, we could check if modern.patch.config exists and prompt the user to update the modern.config configuration and then remove modern.patch.config.

Before we do that, though, I think we need to check if we need to resolve some simple errors and exceptions directly for developers.

[chenjiahan]

On each build, we could check if modern.patch.config exists and prompt the user to update the modern.config configuration and then remove modern.patch.config.

Sounds like it's just writing the correct config to disk, not much different from writing the correct log to the terminal...

we need to check if we need to resolve some simple errors and exceptions directly for developers.

Totally agree, most of the time we should only throw errors for incorrect usages.

[targeral]

Sounds like it's just writing the correct config to disk, not much different from writing the correct log to the terminal...

I feel like this experience would be better if the user only performed the build task once and it succeeded 😄.