Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Quick start needs a cleanup #535

Open
nareshbhatia opened this issue Mar 22, 2022 · 0 comments
Open

Quick start needs a cleanup #535

nareshbhatia opened this issue Mar 22, 2022 · 0 comments
Labels
help wanted Extra attention is needed

Comments

@nareshbhatia
Copy link

Describe the bug or question
I am following the Quick start to get started with single-spa. Unfortunately the experience is anything but quick start :-(. Aside from the final application throwing a runtime error, I had to make multiple choices during the tutorial which made me wonder if my choices were correct.

To Reproduce
Following the quick start directions as best as I can, I am getting the follow runtime error:

Uncaught Error: application '@single-spa/accounts' died in status LOADING_SOURCE_CODE: Unable to resolve bare

Expected behavior
Quick start should be clear and precise. The goal should be to get people started in under 10 minutes. Currently the quick start gives too many choice, perhaps assuming that people are going to use it for real projects. I think generally quick starts are used for learning a new platform and hence my recommendation would be to reduce all optionality in favor of predictable output.

Here are some suggestions:

  • Before creating the root config, suggest to create an umbrella folder, e.g. single-spa-quick-start. This will help keep the tutorial contained in one folder.

  • Suggest a name for the root-config folder, don't leave it as a variable. Will help in referring back to the folder name later.

  • For the purpose of quick start, don't make the layout engine optional. Suggest to answer yes to this question.
    CleanShot 2022-03-22 at 15 57 34.

  • I would also suggest to specify the framework to choose (React, Angular, ...). Doesn't matter much just to get started.

  • Under "Create a single-spa application", suggest a name for the folder and a name for the module. Again this will help in referencing folder names later.

  • Once I ran the single spa app, it showed very scary messages like "Your Microfrontend is not here" and terms like "integrated mode" :-). Is this expected? Do you want to throw all this terminology at a newbie user? If not, prepare the reader for it. Do they really need to follow the instructions on this screen?

CleanShot 2022-03-22 at 16 29 29

  • Under "Add shared dependencies", there is no indication which file/folder to find the import map in.

  • Under "Register the application", step 1 says "add your application to the import map in src/index.ejs. The application's package.json name field is recommended". This is not enough for a newbie to create the entry. If the earlier sections provide more specific folder/file names, this step can be made very specific.

  • Under "Register the application", step 2 again has 2 options depending on layout engine choice. This is not adding any value. Just go with layout engine choice and make the instructions very specific.

After all these steps, the app better work :-) Otherwise the first impression of the package will not be very positive.

Hope this is helpful.

Screenshots and/or console output
If applicable, add screenshots or console output to help explain your problem.

Additional context
Add any other context about the problem or question here.

@filoxo filoxo transferred this issue from single-spa/single-spa Mar 22, 2022
@MilanKovacic MilanKovacic added the help wanted Extra attention is needed label Sep 27, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
help wanted Extra attention is needed
Projects
None yet
Development

No branches or pull requests

2 participants