Need detailed description how the automatic mounting and app rendering works.

[casamia918]

What is the current behaviour? At now, the template project made by preact-cli do not call render function of preact library. At index.ts, it just export App component, that's all.

What is the motivation or use case for changing this behaviour? As I'm a react developer, knowing how the root app component mount to the document element is important. Preact official document also says about how to render preact component into document. But when I created new project using peact-cli, the render function is missing. I spend 3 hours to find "Who did in charge of the app component mounting into the document?"

Describe the solution you'd like Just more detailed description, please.

[rschristian]

I'm not really sure in what way detail could be added? We simply skip the boilerplate of having the user call h() on their app themselves. There's nothing really more to it than that.

This isn't something that only exists in Preact-CLI, plenty of other build tools do this too, as it's generally a nicer user experience. While CRA elects to have users call render(), plenty of other React build tools take the same route as we do here.

[casamia918]

I'm not really sure in what way detail could be added? We simply skip the boilerplate of having the user call h() on their app themselves. There's nothing really more to it than that.

This isn't something that only exists in Preact-CLI, plenty of other build tools do this too, as it's generally a nicer user experience. While CRA elects to have users call render(), plenty of other React build tools take the same route as we do here.

Not every developer knows that automatic rendering is natural behavior of the build tools. As this preact-cli aims to be official command line tool for the preact, describing about under the shell feature in the document is important to the newcomers like me, especially that the feature is about to the initial app mounting and app launching feature.

For example, nextjs is also doing automatic app mounting. But they have detailed document and have mentioned about how to customize root App component and Document Page. By this, newby knows how the nextjs makes their first step of initializing.

Let assume you are a react developer who did not know preact before. First, they meet preact and want to create new project using boilerplate code. Ok, preact-cli is official boilerplate, so install it. Preact also has render function where the preact root component will be mount into document element. Almost same as react, that's good. So you look into project code from preact-cli, to customize the mounting element, for any reason. But there is no comment how to do it. Then they should spend so much time to find the answer.

[rschristian]

If you have the time/know how, feel free to open PRs for the docs that you think could be improved. Many of us have moved on to improve WMR and that's where a lot of time is spent these days. Unlike Vercel (NextJS) we're not a company selling/promoting a product, so it's not unlikely that our docs aren't as fleshed out in some aspects. Always happy to take community contributions/corrections if they can be provided.

Couple things:

As this preact-cli aims to be official command line tool for the preact

It's not really "official", just a tool that we offer. We also offer WMR, a newer build tool. They're "official" in the sense they come from the PreactJS team, but I don't think anyone will necessarily encourage you use our tools over any other offerings.

Ok, preact-cli is official boilerplate, so install it.

Hopefully you didn't actually install it, but used NPX, i.e., npx preact-cli create .... Just trying to move people off npm install -g ..., as that's not great for project init.

[rschristian]

I should also ask, what is it that you're looking to customize here? Might be able to at least set you on the right track if our docs couldn't.

[casamia918]

@rschristian I don't know why are you so offensive to me. I just heard about preact yesterday, and want it to know what is the differences with react, why preact is so faster than react and so on.

While creating first new toy app , I can't find where the "render" function called. To me, knowing the initializing process of the app is important because it is the starting point.

So, I'm comfused. Is this preact handle of the root component mounting? Oh no... document clearly says about render function. Is this convention to have App.tsx file of this preact-cli library? Hmm.. not sure. Lots of question brought out to me. Finally, I found one line of document at the feature list. "Automatic app mounting, debug helpers & Hot Module Replacement".

I don't know enough what the preact is and how the preact-cli works. But I think my situation will be commonly faced problem of the new comers like me. That's why I posted this issue. Surely, you or other maintainers are better than me about what preact is and how the preact-cli works.

From your comment, I got to know that the preact team is moving to WMR project. So, I should read the docs and follow the tracks of your team. This project is interesting. Also, thanks for your feedback.

[rschristian]

Offensive? Sorry, but I do not know what you're referring to. I can only assure you that nothing I've written is meant to be offensive, or anything even approaching that.

Oh no... document clearly says about render function.

There's a difference from reading the docs of the UI library and reading the docs for the build tool. The build tool can make assumptions about what you want to do, hence skipping having h() in user code.

Is this convention to have App.tsx file of this preact-cli library?

You could name it anything. It's just the default export from src/index.{js,ts}.

But I think my situation will be commonly faced problem of the new comers like me. That's why I posted this issue. Surely, you or other maintainers are better than me about what preact is and how the preact-cli works.

I personally don't have the time to invest here, not sure if anyone else does, but this is a community maintained project in many ways. Best way to improve is to write a PR if you can. If not, no worries, we'll just leave this issue open here.

From your comment, I got to know that the preact team is moving to WMR project. So, I should read the docs and follow the tracks of your team. This project is interesting.

Just FYI, that tool probably does more "magic" than even CLI here, just a bit of forewarning.