This year, it was really unprecedented pressure for me. Before, when the company met the demand, most of the cases were based on the schedule. If the schedule was tight, I would arrange and deal with it.

BUT!!! After coming here, the general situation is as follows:

There’s a requirement here to deal with. What? Other tasks? That’s not very normal;

Priority? Parallel! All important, parallel is normal, I also have several things parallel, the DeadLine is XXX;

Have a look? Organize a document to describe clearly, so that precipitation;

Do you have an address for that requirement you made last time? Do you have relevant introduction? Do you have implementation steps? It’s not clear. You write a document;

Hi all, there’s a place here where I think it’s very piecemeal and it’s not good… That is bad… I think so! B: Well, you follow up on this matter and deal with it as you wish.

Here, I made a new library to unify the collection.

Wow, good, then we can use this process to load the framework, you have time to deal with it?

However, the impact surface will not….

The reconstruction is finished, and it has been sent to pre-delivery for half a month. Some business requirements are already dependent on this part of changes, so we need to prepare a wave of online changes? You can’t send it directly like this, because the risk is too high. You should sort out an online plan and do a regression test for the support pages of several domains on the current online.

There’s a new technology here, right? You take the time to research, write a document, prepare a sharing session;

What’s wrong with the recruitment lately? In this way, everyone in the evening 21-21.30 everyone together collective resume.

Communicate KPI. You have done a lot of things in the past six months, and the effect is good. Your colleagues also give you a high evaluation. But they are scattered points, without a surface output, looking forward to your later more outstanding performance;

How can we have a surface output, give some guidance? How about you first write a detailed document of all the things you have done in the past six months for me to look at, AND I will give you some suggestions;

A beautiful dividing line

Okay, I was going to write a couple of quotes, but I didn’t expect to write so much. Shout ~ suddenly a kind of discharge a body toxin feeling, cool! Ha, ha, ha

I’ve been thinking a lot about what I didn’t do well this year, or what I didn’t do as well as others did.

Well, at least at this point, I’m still thinking about how to improve, unlike before when I thought I was doing so well that no one else could.

Taking advantage of our day off and some free time, let’s talk about technology.

background

Around June of ’19, I published an article called “First Taste of Bit”. In the process of combing through this article, I can say that I had a deep experience with the concepts and practices proposed by BIT. It was like a seed planted in my mind, and I didn’t think it was anything at first.

I remember the first time I shared bit with my colleague, he said:

Emm, with all your talk, I don’t think it’s that… Functioning?

Don’t feel like eggs are useful?

Ah, Emm, now that you say it, it’s like you said it. I think if we introduce bit now, it will bring a lot of extra work to our daily work.

This reaction is normal. I saw the bit on Vue’s official website in early 2018, and I clicked on it to browse it briefly. My feeling at the time was that there was no use for eggs, just “front-end vertical Git”. The situation of domestic support is not so good, even a decent Chinese document can not be found.

It wasn’t practical for our team to jump right into the bit workflow, because so much of the infrastructure in the company didn’t know about the bit.

However, the practice and concept of BIT are very valuable and can be used for reference.

Therefore, I want to do one thing, step by step to introduce the gameplay of bit in a way that we are familiar with and even extend it, so that we can recognize its benefits and value.

To know the component

With the brewing of the concept of “micro-front-end” in recent years, more and more teams begin to process their business into different components, and then orchestrate them into a business page through certain front-end practices.

Maintenance of components becomes more and more important. So, let’s take a look at how most teams maintain components today!

  • Large library type, Antd, Element standard large library type
  • A one-time, fully business component that is used once and never maintained again
  • High reuse type, at first sight should be individually packaged for other people to use, such as: video player
  • Repackaged, some libraries are written with native JS, wrapped and imported directly as components
  • Project fusion, together with business projects, mixed store, regardless of you and me

These are the only types of components I can think of for now, and if your team is maintaining its own component library, it should be easy to understand what I’m saying above.

I believe that since I have done so, there must be reasons and benefits for doing so. No one will sit around looking for trouble to do something wrong. So what are the benefits and pain points of these practices? Let me analyze it from several aspects.

Convenient and quick

Components, of course, is the fastest to run, the most convenient to see the best effect. For that matter, what faster way is there to bundle components directly into a business project? ?

Now use a display panel and go to the Components directory right away.

The data? Isn’t there a store? Bring it in and you get the data!

What you see is what you get, now you can see the effect on the page! Can’t argue with…

Sure, developing this component is fast, but is it really the fastest in terms of overall business requirements implementation? If this is the quickest way, why do so many teams emphasize precipitation, encapsulation, and abstraction?

In fact, many components at the time seemed like they could only be used once in a lifetime, without encapsulation. But often when the interactive manuscript comes, I will find that this style looks like I have seen it before. Then go to a variety of business items, wow finally found, copy over to find a variety of hot, fixed eyes, store??

So, the smart team has insight into all this, let’s maintain the components in the same place, and then we write a good document, when using from the library surface can be taken, if there are bugs unified repair is, great 👍!

maintainability

As a result, we will be in full swing to start the component abstraction, component rectification of the vast project.

In the beginning, there’s usually one of the more reliable, competent guys on the team (huh? Why me? Take care of Webpack, Babel, TypeScript, Sass\Less, directory structure, unit test structure, code specification, Review specification, and release specification, and write a standard component. Write unit tests.

For maintenance, all the components are written in a repository, and then use the project direct introduction, business problems gradually divided into components or project problems, and even some requirements can use this interaction has similar in the component library, it is ok to use that component, to dismiss 😏 products and design.

In the use of the time, one day found, ah, how our component library packaged out of 10m ah 😱!

Then I found a reliable, competent young man (yes, me again) to look up, who introduced this library? Doesn’t this component already have one? That’s not how Lodash works! What does this component do? Why is there no documentation?

With hundreds of business components, you can only marvel at how quickly the business can iterate.

So, large database maintenance is a large database maintenance benefits and applicable scenarios, we can have such abstract thinking is already a technical breakthrough, now just encountered another problem, solve it!

Component size, load performance

It is easy to find out exactly what packages are “hogging” so much traffic by contacting some of WebPack’s peripheral tools, such as Analyzer.

There are also some components in the original package that should not be maintained in the large library, such as disposable components, repackaged components.

This component may introduce a large third party dependency, such as video player, Banner Swiper, etc.

The best way to deal with such components is to create an independent repository, complete the packaging, write a README, and publish it to the Intranet NPM for use by business projects.

But you know, it would be too expensive. If I had time, I’m sure….. balabala… (Generally speaking, if you tell a programmer a better solution, unless he was involved in designing the solution, the majority of responses are 🙄)

There are many other ways to address component size, such as asynchronous loading, NPM import, load on demand, etc. So, let’s talk about another important part that is often overlooked.

Component description and indexability

Boss, we have accumulated 200+ components this year, some of which are very good, and have supported 20+ projects at the same time.

Wow, that’s great! Can you show me what your component looks like? Ah, this, look at this page we made, this page uses these components, Balabala…

Design: I heard that you have deposited 200+ components, can you show us which ones? We can refer to these components for output in the next design to reduce communication costs.

Front end: @Owner Do we have this component in our library? Yes, CascadeSelect. Oh, how does it work? Is there documentation? . Look at the source code. well.. 😅

Component specification and indexability are actually second only to component availability, or even higher.

Imagine today that you wrote a great component. Reusability, interface design, and interaction design were great, but did you have a way to get people to know that right away, or did you have to hold a meeting about it? Today, I would like to take an hour of your precious time to introduce the great component I wrote today. 🤕

On the other hand, if I’m writing a component, it’s not going to be any good, and no one else is going to use it, so I don’t have to document it, and no one will know. Oh huo, balls egg 🙃

Index component to share an image:

How happy and enjoyable it would be if one day your team’s component library could be like this, with all the rules and facts!

I know it’s good! Who doesn’t know! If I had time, I would certainly…. balabala…

So what you’re saying is that every time we write a component, we need to add documentation, instructions, and screenshots! ?

Yes, build a separate library, and consider configuring Webpack, Babel, TypeScript, Sass\Less, directory structure, unit test structure, code specification, Review specification, release specification 😎

Ha! Ha! F * CK!!!!! AWAY!!!!! 🤜

The most * practice

So much to say, mainly want to bring readers together to think, is also my writing style (like to tell stories), most of the content is actually front-end ER will encounter problems.

Then into the main topic, said a lot of problems, there must be some way to solve it!

Bit has built-in webPack and some plug-in loaders to solve React and Vue compilation problems.

For our team, React is used, so let’s start with a React scaffolding.

If each component is released as a separate NPM project, the first thing to consider is a set of build environments on the front end. If I have N front-end component projects, each front-end component library webpack, Babel and so on need to be configured repeatedly, it is really a big deal, I just want to write a component, why bother. So our scaffolding starts with some basic compile commands.

By the way, scaffolding doesn’t have a name yet, so let’s call it comp 😷

  • Comp New handles creating a standard component from the template

    • Initialize a standard component project structure, all connected to all comp commands

    • Initialize the Git repository

    • Initialize the CI/CD cloud build configuration

  • Comp Start handles daily development, plus individual component presentation and debugging capabilities

  • Comp Watch handles Babel and SCSS listening compilations for NPM Link scenarios

  • Comp Babel handles compiling NPM packages

  • Comp dev handles listening to compile umD packages for proxy debugging

  • Comp Build handles the final compilation process

    • Webpack compiles UMD packages

    • Babel package

    • CI\CD process automatic screenshots component

    • CI\CD process automatically generates README

    • Other Hook

  • Comp Test handles JEST unit tests

After the component is initialized, the directory structure looks like this:

export default function(Component: typeof IComponent, mountNode) {
  /** DOCS_START Please write the Demo generation method in the following block to generate README and Riddle **/

  ReactDOM.render(
    <Component
      navigation={true}
      pagination={true}
      autoplay={true}
      dataSource={[
        {
          href: 'http://xxxxxxxx',
          image: 'https://xxxxxxx.cdn.com/tfs/TB1jHkBmNv1gK0jSZFFXXb0sXXa-1440-343.png',
        },
        {
          image: 'https://xxxxxxx.cdn.com/tfs/TB1Y_XacrY1gK0jSZTEXXXDQVXa-1416-813.png',
        },
      ]}
    />,
    mountNode,
  );

  /** DOCS_END **/
}

Copy the code

There is no webpack\ Babel configuration in the project structure, of course, if you have special configuration requirements, you can set up comp.config.js to configure (here reference many existing CLI processing methods).

The advantage of this approach is that after the project is initialized, the directory structure is very clear to the user, there is not much configuration allowed in the project, and the compilation environment for all components is almost guaranteed to be uniform.

These are very basic functions, but of course they are indispensable. I won’t go into the details of these basic commands, but I will focus on them later.

Introduce features through these questions:

What is your usual component development process?

Usually, the general is according to the design draft, cut to the component.

Then go and create the component, and finally introduce it through the project, and develop it as you watch.

How did you validate the Props you provided when you were developing the component?

The simplest thing you can do is make a mock.

Or write a unit test?

Is the process of writing Mock a Usage?

This should also be counted, but these are scattered in various projects, and some mocks are deleted after verification.

Who has time to add this to the README during development?

Why don’t they document it?

Are you sure? Because you’re lazy?

Then why didn’t you write it? Emm, that’s because…. Write a document this matter, write may not be read, also take time ah! There are so many business requirements! If I had time, I would definitely…. balabala…

OK, let’s move on to the next question

What parts does a good component document need?

Develop component background, note what, this does not have what too big necessary, some components need to supplement, if not, do not need to supplement.

Some of the main needs are: usage, Props entry, preferably a screenshot!

There are installation, development, compilation of the command to introduce it.

The icing on the cake would be a few badges. Let’s introduce the source TypeScript and how many downloads.

It’s too much trouble to update the documentation. The Props information can be found in the Props component. I have some comments and type definitions.

After a round of soul-searching, you realize that during the development of the component, the reason the developer was so clear about the component was that the developer had already written a README for himself.

  • Usage: need to see the effects during component development. Have you written some mock data, and know which props to pass to produce what effects
  • Props: What Props does the component have, what does it represent, and what is the type of each prop parameter that is reflected in TypeScript Interface and comments
  • Screenshot: Have mock data and don’t know what it looks like? We’ve seen n-multilateral

With these three most important introductions, most developers should know what this component looks like.

So, if we can collect all this data, can we use scripts to generate README documents automatically?

Usage/Usage

Collecting Usage is easy. If the component had the ability to develop independently, wouldn’t it be possible to keep the Mock Usage data

For those of you who don’t understand what I mean by “the ability to develop components independently,” let me explain: when we develop a component, we usually put the component on a page and debug the component over and over again. Developing components independently means that you can launch a page and see what the component looks like, which presents all the information surrounding the component.

So in scaffolding, as long as you write the mock data you need to debug the component in docs. Ts, the page can show what the component looks like, and the mock data can be retained as README document data.

In addition, it is possible to generate code directly from CodePen, Riddle and other online edits if the output of the demo interface is consistent.

Imagine if a paragraph appears in your README: click to experience immediately, jump to the past can be edited online to see the effect in real time, it is a kind of enjoyment for any students to see your component 😉

Component parameters/Props

Gathering this data is a bit more complicated. We need to drill down into the TypeScript AST syntax tree to extract the types of component props and comments for interfaces.

After a bit of github, we finally found a niche library that can implement react-Docgen-typescript to handle this

During the development process, some of the comments and type output was not what I expected, so I forked and made some changes. I was able to complete the analysis of a complete component and output a Typefile.json.

Similarly, with this capability, we can extend the webpack plugin react-docgen-typescript-loader to add the __docInfo attribute to the static attribute of the component to declare its attribute content, so that the component development process can achieve the following effects:

Screenshots/Preview

Have components, have demo, still worry about screenshots?

Puppeteer directly in the build process, read and run docs. Ts to render the components, take screenshots, then send to CDN with the cloud build CD process, and you’re done!

Finally, add some special tags to the README that can be generated as a README replacement during the cloud build process. Does not affect what the README itself is telling you.

Finally, Duang! A complete, beautiful, and detailed document is generated. We didn’t write anything about README specifically, and everything is easily and standard output.

conclusion

In all of this complexity, it looked as if I’d ended up with a README that automatically generated itself. But really, README is just a by-product.

During the whole process, I have obtained all the data I want for this component, including its Props, Usage, Preview, version information, package name, and even the UMD CDN package and NPM package of this component will be released synchronously during the construction process.

You can then build and extend many features and platforms around this data and tools.

To name a few chestnuts:

  • Build a bit-like component platform, collect the components within the team, display and index them in a unified platform
  • Build a visual platform based on the Props type information, pass the Props parameters directly to the user to set, and provide different Form setters according to different data types
  • It looks like components are distributed in different libraries, but you can use the component CLI to do a uniform build process
  • It is very easy to access the microfront-end framework because all component release builds are standard build protocols
  • Evaluate code quality by counting component releases, downloads, and associated bugs

Currently on our team, we have used the tool to produce 30+ usable components, and the release components have been successfully plugged into our existing visual editor.

Take a look at the visual Settings panel:

I’ve found that developers are happy to explain and polish the Props 😊 as long as the implementation doesn’t require too much work for developers and gives them something that can be seen in real time.

The components that our team has produced so far look clean and tidy.

In addition, because the scaffolding born time is still short, need to improve the place is still a lot of, has not met the company’s open source standards, do not take out the shame 😊, but I think the overall idea is more valuable for reference!

I am a life loving front-end engineer, personal blogger! Yooh! 🤠

Now, as a matter of course, I should put up some job listings, okay?

Ali international recruitment in Taiwan! Front-end, Java requirements P6 and above! If you are interested, please send your resume to us

[email protected]

We look forward to your participation ~😻😻