[WIP] Typescript definitions

[HoldYourWaffle]

I'm currently in the process of researching existing template engines/html pre-processors to use in my express-based application. My base requirements are:

• Template inheritance (block/extends system)
• HTML-tag based syntax

I've noticed 2 projects so far that satisfy these requirements: PostHTML and reshape. (If there are more projects that I have missed I'd love to hear about it 😉)

I'm trying to make up my mind on which library to choose (or perhaps even create my own). I came across this project about 10 minutes ago, and it seems like it has much higher code/documentation quality than PostHTML. On the other hand, PostHTML seems to be more mature an popular, as well as a bigger collection of plugins.
Maintenance is also an issue. There doesn't seem to be any activity in the past year on both projects, although for all I know they could just be feature complete. I was hoping you could shine some light on the current maintenance situation for both project (I noticed you've contributed to both).

In short: why would I choose this project over PostHTML (or the other way around) and are these project still maintained?

[jescalan]

Hey @HoldYourWaffle!

Great question! This project originally began as a contribution to PostHTML actually, but included several breaking changes that their team was unwilling to accept, but I felt were necessary for my use cases, most importantly a parser that traced location information so that errors could be reported pointing to a specific line both out of core, and in plugins.

In general, the upgrades I was working on making, as you called out in general, were to make a bit cleaner and more well-structured codebase, with much better tests across the board, in addition to better error reporting. This worked, and reshape went into production on my team's work and has been stable for years.

As far as maintenance, I am personally starting to move towards a jsx-based html rendering pipeline for my full-time work projects, so I won't have as much sponsored time to contribute to this project as I once did. That being said, it's quite stable and has been for years, and if there were anyone interested in new features or contributions, I'd still be perfectly happy to discuss it. I love this project because of its simplicity and elegance (parsers are just so great), and feel like in general, it is easy and enjoyable to work on.

For PostHTML, there is a larger and more committed team working on it, and much of its popularity stems from the fact that it was "first to market", and that it is (or at least was?) part of the bundler parcel. I know their team is committed to the project and passionate about it, at least last I checked, but I do have several reservations about the rigor of reviews and testing requirements that contributions need to go through to add to the codebase.

I haven't really marketed this project very much, I have sort of been disillusioned by the prospect of marketing projects that you work on for free and then other people complain about, so that may be part of the reason behind why it is not super popular -- anyone who found out about this was pretty much via word of mouth, or conference or meetup talks where I talked about the process of building it, which was interesting. If you are interested in it, you are more than welcome to use it -- it's stable, the codebases of the core and all plugins are high quality. However, you should be aware that in general I approach open source maintenance in a fairly passive manner -- that is, if someone is asking for a change of feature I am happy to talk about it, help out, and review, but I prefer that the requester take the lead on the actual implementation. To be honest, I think this is a safer approach to open source in general anyway, since you don't get support guarantees with any OSS project, so diving in, understanding the codebase, and contributing is a much better way to be secure in your use of a project.

And finally, there is one other similar project that the brilliant @jonathantneal has been working on that can be found here: https://github.com/phtmlorg. As far as I'm aware, his focus with this project is to build out a more robust collection of helpers attached to the AST nodes, following the way that postcss does it.

Hope this is helpful, and good luck in your search!

[HoldYourWaffle]

Thank you for your comprehensive response!

I decided to choose reshape, mainly because the documentation is just so much better. Although the plugins are less in number and maturity they seem to be of much higher quality, and using them so far has been a great experience!

The only "issue" I'm having is the absence of TypeScript type-definitions. I now need to figure out what kind of input each plugin wants (and write a small definition) before I can use it. This is of course a one-time effort, and I'll see if I can contribute my work to either DefinitelyTyped or the corresponding repositories directly once I'm sure that they're accurate.

[jescalan]

Great to hear! I would be very happy to accept directly typescript defs for any part of the ecosystem as well, and ship them with the packages.

[HoldYourWaffle]

I'm currently doing a more in-depth analysis of how reshape does it's magic and so far the experience has been surprisingly pleasant. The only thing I'm really having trouble with is understanding the actual "data flow"/relations inside the code.
The documentation is pretty good (particularly from a 'using' perspective), but I'm having trouble reasoning about the actual module code without going back to the README every 10 seconds. For example, there are some (internal) structures/functions/relations that aren't explained (well enough). Normally this wouldn't be a problem, but it makes it practically impossible to write accurate TypeScript definitions.

To help with this problem I'm writing the definitions while I'm trying to understand it. This helps, but it's still hard to reason about the actual module code. This in turn makes it harder to update/add to the definitions, which makes it harder to understand other features.
There are 2 possible solutions to this:

1. I somehow learn the exact data structures Reshape uses and expects, either by finding additional documentation or asking (probably a lot of) questions to you directly.
2. Rewriting Reshape (and it's plugins) in TypeScript.

I think option 2 would be the better solution here. I have no idea if you're familiar with TypeScript, but I hope you'll at least consider it. I'm biased towards using TypeScript for many reasons, but here is a selection of pros and cons to help you make an (informed) decision:

Pros

• Code becomes largely self-documenting
• Potential bugs can be found quicker due to the compiler screaming at you for doing stupid things (this isn't that big of a concern for this project since it's relatively small and easy to test)
• It becomes a lot easier to verify that a plugin is compatible with a certain version of reshape. If data structure/function parameters/etc. don't match the compiler will just scream at you. This is of course also done by tests, but in my experience it's easier to read an error message about missing properties than vague "xxx is undefined/not a function" errors from tests
• The code becomes easier to understand, because data structures and especially data flow becomes a lot more explicit (without being more verbose). This is especially good for plugin development.
• Maintenance will be a lot easier down the line
• Better typescript integration (obviously)
• (In my opinion) better module syntax with ES6 modules
• You're probably a busy man, this way I won't have to bother you with all kinds of random questions

Cons

• TypeScript requires an extra compilation step (TS → JS)
• You'll need to learn to read/write TypeScript, although this very simple, this page should be enough to get you started.
• Someone needs to put time and effort in converting all existing plugins. I understand that you probably can't/don't want to do this, I'm 100% willing to do this myself. It'd definitely take a long time, but as long as the actual API doesn't change the old JS-based code should work without any issue.

So what do you think is the best option? I'm fine with both options as long as I somehow manage to understand how reshape works eventually. In my opinion this would be easier by rewriting the module in TypeScript, but if you don't mind me asking a ton of questions it doesn't matter all that much in the end.

On a completely different topic: you mentioned you're using a JSX-based rendering process now. Could you share some more details on what you mean by this? I've been looking into the possiblity of a JSX-based solution to make transforming database objects into user-presented HTML easier, but I haven't found anything yet that is useful but not bloated or killing performance.

[jescalan]

Sorry for the late response here, but if you are willing to rewrite everything with Typescript, I am ok with this!

As far as my own render process, for my work I am using react and it makes more sense to run a full react-based pipeline. I worked on a bit more of a hybrid approach here as well: https://github.com/reshape/react-components

[HoldYourWaffle]

That's great to hear! I'm really busy right now with the project I mentioned earlier, but I should be able to start on the rewrite somewhere next month.

I am using react and it makes more sense to run a full react-based pipeline

So if I understand correctly you're using react server side rendering? I've been looking into this option myself, but it seems like a really bloated approach to me (an outsider who has just started using react), how is the performance?

[jescalan]

So if I understand correctly you're using react server side rendering? I've been looking into this option myself, but it seems like a really bloated approach to me (an outsider who has just started using react), how is the performance?

Yes, the performance is excellent. If you are only building a normal static site though it is unnecessary.