Lack of appropriate README

[propkitty]

This repo has been left all over the speed-measure-webpack-plugin issues, but there is little to no information on how this should be used when coming to the page. An improved README would go a long way to making it so people could appropriately test this possible successor.

[ShuiRuTian]

Ah, I think there is a not bad README file in fact: https://github.com/ShuiRuTian/time-analytics-webpack-plugin/tree/main/packages/time-analytics-webpack-plugin

Could this README resolve your problem? If not, what else you think could make the readme better?

But you are right, maybe I need to make this README file more easy to access in the root page....

Why it's not in the root page:

The main purpose is to give a good README page in npm website, which is my prefer way when I want to read the info for a package.

[ShuiRuTian]

Will close this issue after one week if there is no response.

Thanks for the feedback!

[FBRAA]

Hello, I think would be great to add the import statement of plugin, like
const { TimeAnalyticsPlugin } = require('time-analytics-webpack-plugin');
as it different from the origin plugin

[ShuiRuTian]

@FBRAA sorry, I could not fully get your point....

You mean we should provide mjs and cjs together? Or We should provide a default export?

[jackykwan-eventx]

i think the Readme is not showing enough information
We can take a look at speed-measurement, they show:

• How to install
• How to import to webpack config
• How to apply in existing code base (usage)

https://www.npmjs.com/package/speed-measure-webpack-plugin

Tbh, i can not find how to use this package in Readme

[FBRAA]

@FBRAA sorry, I could not fully get your point....

You mean we should provide mjs and cjs together? Or We should provide a default export?

Readme should have information on how the import statement should be written in order your plugin to function.

As a fresh user, I firstly tried:

const TimeAnalytics = require('time-analytics-webpack-plugin'); 
const Plugin = TimeAnalytics();

it didnt work

then I tried

import TimeAnalytics from 'time-analytics-webpack-plugin'); 
const Plugin = TimeAnalytics();

didn't work also

then I tried using it as is, because TimeAnalytics() could not be function;

then I went to
const TimeAnalyticsPlugin = require('time-analytics-webpack-plugin');

console.logged it and got [Getter], which confused me,

then I had to go through files of your file, calculating more options on 'HOW TO IMPORT' topic,

finally somehow I reached this variant:

const { TimeAnalyticsPlugin } = require('time-analytics-webpack-plugin');

So, if there are options on how to import your plugin, they should be listed. If it is the only option, it should be written to README as well.
As far as I can see, most of plugins are imported to my project this way, and so was speed-measurement one. Maybe it would be good to make your way of import look same:

[ShuiRuTian]

@FBRAA Thanks for the detailed response!

You are right, I missed this part. The README is updated now. Please feel free to give more feedback if you think it's still not good enough.

But it's intentional to use "named export" rather than "default export". Although we only have one object exported.

The main motivation is to use IDE function -- auto complete. If a package uses default export, there is not an "official name" and you need to type a proper text as the name.

Like in

import TerserPlugin from 'terser-webpack-plugin'

you always need to type "TerserPlugin". And any other text is valid, it's just your choice.

But if a package use "named export", then you could trigger auto complete like

import {/* Trigger auto complete here */} from 'my-plugin' // in VSCode, use ctrl+space to trigger

The only valid "official name" could be used. If you want to rename the export object, you need as keyword.

[ShuiRuTian]

@jackykwan-eventx The README is updated.

Although I think we did have "How to use" section...

Any more feedback is welcomed if you think it's still not enough.