Legacy Node.js libraries in MDN docs

[tshemsedinov]

As of 2022 express is outdated but we have learning materials for it: https://developer.mozilla.org/en-US/docs/Learn/Server-side/Express_Nodejs

[hamishwillee]

@tshemsedinov That's a very provocative statement. What is it you would like to see as well or instead?

My understanding is that:

• Express is one of, and possibly "the most" widely used nodejs server framework.
• It has a fairly flat adoption curve
• It is very stable and has a huge number of support libraries.
• It gets regular updates
• It is the basis of numerous other frameworks.
• It is a good "gateway" framework for new users to learn the common concepts by many of the frameworks that followed it.

I am not arguing that there aren't more recent frameworks that have great abstractions. I do however think that Express is great for showing the concepts, and that while you will be able to find millions people who agree there is a better framework, you might have trouble getting them all to agree what it is :-)

[tshemsedinov]

There are many frameworks much better and much worse in npm, I just want to tell that frameworks become hype and outdated too fast.
In early node.js days we needed frameworks because the platform did not have many tools, but now node.js has everything we need for creating advanced http API server out of the box. As of 2022 examples with pure node.js will be shorter, clearer and even ьгср more simple and understandable for beginners than with Express. Moreover, Express brings extremely bad practices:

• Middleware pattern is a broken Chain-Of-Responsibility pattern from "Gang of Four"
• All its functionality is based on mix-ins to request and responce, its api added with mix-ins
• Mix-in provocation for the applications based on the top
• Reference pollution and shared state provocation
• Race condition provocation
• Abstraction leak provocation
• Fat controller provocation and mixing everything in a single layered
• High coupling provocation
• Error ignoring provocation

I propose to add pure node.js examples and compare @hamishwillee

[tshemsedinov]

Additional anti-patterns you can find even in Express docs

• Temporary field
• Shared state
• Global state
• Inappropriate intimacy
• Pass-through parameters
• Data clump
• Accumulate and fire

Instead of this it would be better to have examples with DDD and "Clean architecture", layered approach and business-logic in the middle isolated from any framework. It is easy to write framework-agnostic code and even protocol-agnostic, so any framework can be plugged as non-important detail of implementation.

[hamishwillee]

@tshemsedinov Obvious question then - if "raw node" web servers are so much better, why do the vast majority still use frameworks? I suspect in part because a web search on "how do I do a web server" tells them too. Also because there are many examples out there and not so many good servers written in pure node.

This is a good argument for you doing a pure JavaScript web server tutorial, in particular if it works through the same/similar "real world" example like the local library we have used for Express and Django. Those are good because they work though the common things in most frameworks - routing, database integration, templating, session implementation, authentication, deployment etc.

I'm not sure whether it would make sense to have it in parallel or as a replacement to Express docs. I doubt we'd consider removing Express any time soon, but I'd reserve judgement. NOTE, you could also find people who would argue MDN shouldn't have anything that isn't about web standards because of these kinds of discussions.

I'll give some other contributors on MDN a chance to comment.

[tshemsedinov]

That's just an inertia, at the very beginning all guides and books was about frameworks, not the node itself. But not it became a problem. People know little about node.js internals, they write code not on the top of node.js, but on the top of frameworks. Although most frameworks are very outdated and do not use modern features such as worker_threads, web streams API, async hooks, context isolation, etc., even modern features of JavaScript like classes, asynchronous functions, for-await are not used in almost all frameworks. There are a few modern frameworks, like Nest.js, they introduces "Layered architecture" and "Domain-driven design" but unfortunately they are not so modern in adopting new platform capabilities (not even that new, 5 years is a enough for feature stability and maturity). What I am trying to do is move the attention of programmers to the native node.js API and internals. @hamishwillee

[ddbeck]

Reading the discussion here, I'm seeing two distinct questions:

1. Should we retain documentation for Express?
2. Should we have a framework-less server side JS guide?

I don't think these questions are going to be answers to each other—it's too many moving pieces. Instead, I think we'll need proposals that address each question on their own terms.

If you want to drop Express docs, we need a detailed proposal that speaks to:

• Evidence which shows that Express is outdated or that our docs covering Express are outdated (to understand why we'd do this)
• Impact to MDN readers of the existing content and how we might mitigate negative effects of removal (to understand how it helps readers to do this)
• A list of tasks to complete to remove the docs (to understand how much effort is required)

If you want to develop a framework-less guide, then we'd need a proposal to cover:

• Evidence which shows that such content is of interest and benefit to MDN readers (to understand why we'd do this)
• Intended learning outcomes (to understand how it helps readers to do this)
• An outline for proposed content that brings about the learning outcomes (to understand how much effort is required)

[tshemsedinov]

You are right, my proposal for now:

1. Add framework-agnostic, pure node.js examples similar to what we have for Express, so anybody can compare and even take patterns of refactoring and rewriting from Express to Node.js. Maybe in form of table or adding one example after one for ease of comparison.
2. Add notes to Express articles describing pros and cons for all patterns (like middleware and chain of responsibility), for all code examples (mix-ins bad effects, substitutions), and suggestions how can we reduce negative effect of mentioned problems if one can't just remove Express from project.

I think dropping something we already have in MDN is not a good idea because certain URLs are already spread over the network, and it will be not so comfortable for audience, if they will point to 404. But we may learn a lesson and hold oneself from adding frameworks, npm libraries and something that may become outdated rapidly. If MDN docs are in this situation, I think that projects/product and developers knowledge are in a similar situation, so instead of deleting pages, we can mark them as historical and give ways to improve the code. @ddbeck @hamishwillee

[tshemsedinov]

I will prepare a brief list of learning outcomes. And as an author of largest free lectures about node.js I will propose my students and free listeners to help us with all needed efforts.

[hamishwillee]

Add notes to Express articles describing pros and cons for all patterns (like middleware and chain of responsibility), for all code examples (mix-ins bad effects, substitutions), and suggestions how can we reduce negative effect of mentioned problems if one can't just remove Express from project.

I don't agree with this path. The express tutorial is an example of how to use Express: it's not written or intended as a comparative framework evaluation, and should not be.

It is reasonable to question the choices made by any framework. To do that you'd write a section in the new tutorial explaining the relative benefits of the "pure" approach. You would cross link to this from the Express tutorial - somewhere in the introduction.

There this nothing to stop you in the pure node docs commenting how "Approach XYZ" is a better way than [insert framework here] because of [insert reason here] as well.

Something to remember is not just the effort to produce this, which is very welcome, but the ongoing maintenance.