[Feedback] Initialize Amplify DataStore section is unclear and lacking consistency / detail

[JPVan]

Page: /lib/datastore/getting-started/q/platform/js

Feedback:

Hey, as someone pretty new to Amplify, this page was confusing. I think some simple changes in a couple of places could make it clearer much more helpful to beginners.

Suggestion 1:

Add npm and yarn command line examples for how to add @aws-amplify/datastore (and any other required modules to the project during the Initialize Amplify DataStore step.

• https://docs.amplify.aws/lib/datastore/getting-started/q/platform/js#initialize-amplify-datastore

Justification 1:

The DataStore Getting Started section reads a bit like a tutorial (which is nice) up until the Initialize Amplify DataStore section. Just previously, it instructs to use "amplify codegen models" to generate the models.

But here it doesn't give any instructions to do anything, but kind of implies that you're adding DataStore to the project. For someone new to all of this, the guide could be much more helpful. It might be nice to have another command line section showing the npm and yarn commands to add the necessary modules to your project.

I ran "yarn add @aws-amplify/datastore" in the project directory, and then "yarn build" but got an error message that wasn't clear what the actual problem was. (Error output is included at the bottom of this issue.)

The next section carries on as if the documentation had just told you what to do. "Now the application is ready to execute..." So I think the intent is to follow like a tutorial. And whether or not that's intended, I think it would be best as a tutorial since the audience could include those new to Node.

-=-=-=-=- Part 2: Prerequisites section - options 1 and 2 confusion / missing information -=-=-=-=-

Suggestion 2: Add detail and clarification to Prerequisites section.

• https://docs.amplify.aws/lib/datastore/getting-started/q/platform/js#prerequisites

Detail 2:

One other thing that I might have mentioned on another issue, the beginning of this Getting Started page mentions React specifically, but not any other frameworks such as Vue or Angular. It lists two options for setting up prerequisites, Option 1 (which is apparently for React only, but not titled that way), and Option 2, which is apparently for React as well as other platforms, but also not specified that way. Instead Option 2 is just discussed as "another way" to set up your project rather than as the way for Vue, Angular, etc. Even after using Amplify CLI for a few weeks, I'm still confused about the differences between "Platform Integration" / npx script and the Amplify CLI. Why are both even offered? What is each best for? Are there benefits to either or both? What platforms do they each work with? Can Platform Integration work with Vue and Amplify as well, or only with React? Information for other frameworks, or links here to information elsewhere would be very helpful as part of the Getting Started section.

I included suggestions on two sections of this article because they both are about this one page. I wasn't sure if you'd want to make both changes, and if so if separate feedback for each would be better.

-=-=-=-=- Suggestion 3: Combine this page with one or more platform example code snippets (including link to a working repository ideally) so that the entire thing can be followed from start to finish in order to get a simple working Amplify DataStore.

• https://docs.amplify.aws/lib/datastore/examples/q/platform/js

Hope this is helpful. Thanks!
Jonathan

P.S. Here is the error info from the failed attempt to follow the two partial tutorials from the Getting Started section and the Vue Example App. I wondered if I hadn't built the models correctly, but reran "amplify codegen models" without errors and and no files changed.

yarn build
yarn run v1.22.4
$ vue-cli-service build

| Building for production...

ERROR Failed to compile with 1 errors 7:04:22 PM
This relative module was not found:

• ./models in ./node_modules/cache-loader/dist/cjs.js??ref--12-0!./node_modules/thread-loader/dist/cjs.js!./node_modules/babel-loader/lib!./node_modules/cache-loader/dist/cjs.js??ref--0-0!./node_modules/vue-loader/lib??vue-loader-options!./src/views/Home.vue?vue&type=script&lang=js&
  ERROR Build failed with errors.
  error Command failed with exit code 1.
  info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.

[renebrandel]

Hi - sorry for the very late response but wanted to make sure we close this out nonetheless. I've incorporated the suggestion 1 explicitly as part of 5300.

Suggestion 2: We've removed the React mentions from "Option 2" but Option 1 very much works best with React. Since then, we've also split out "React Native" into a separate switcher so that should address this issue.

Suggestion 3: Agree! We've added Angular, Vue examples since.

[JPVan]

Better late than never! Thanks for the reply. :)