For npm/yarn-based build, the CDK should be entirely self-contained.

A source of confusion by people the Gitter room is the interaction between the global aws-cdk binary and project-level dependencies. Systems like create-react-app or Next.js create builds that are entirely self-contained, requiring no global dependencies other than npm or yarn. This workflow is closer to most JS-based workflows today, and allows for the CDK a simple npm update/yarn update.

Additionally, a create-cdk-app package would (like create-react-app or many of its kind) can be used as a template in in yarn or npx can be used to run create-x-app, removing the need for a cdk init-like command for Node-based projects.

[davidbarsky]

Can you give us some insight into how they would work? As in, would users run: npm run cdk deploy Instead of simply: cdk deploy

Roughly, yes—I’ll defer to my personal website that uses Next.js. In reality, most people would run just npm run deploy or yarn deploy instead of cdk deploy. I’ll also respectfully disagree with assertion of “simplicity” for several reasons:

• Introducing a global dependency on a CLI tool that needs to be upgraded independently of a given set of dependencies in a package.json might seem easy in the beginning, but makes managing multiple CDK packages independently becomes difficult.
• A single package.json is no longer entirely self-contained and reproducible.
• The JS community has moved away from global dependencies and instead managed them through a entirely through a package.json. Breaking this trend breaks user expectations.

And is your proposal to make a new NPM package (create-cdk-app) which would generate a template directory structure that has: [code sample redacted].

Yes, and an index.js. I’d suggest taking a look at Facebook’s create-react-app for a pretty solid demonstration of how this works.

[davidbarsky]

There are multiple subcommands for the cdk command-line tool. I’d hate to mirror them all into the package.json {"scripts"} section, so I feel npm run cdk deploy will have to be the command.

Hmm—I don’t think the tree of subcommands needs to flattened into the scripts section—just the most common ones. An alternate solution would be to only mirror the top-level subcommands and ask customers to use -- to access the subcommand.

I don’t disagree that this is probably a better solution for version management for users managing projects using NPM. The word “simply” was not meant to convey an unwillingness to consider your suggestion, I apologize if it came off that way.

No worries! I apologize if I came off as defensive—I think we’re both approaching this in good faith.

On the other hand, we also have users in other language and with other dependency managers though, and they won’t be able to take advantage of the per-project toolkit dependency. We also have to balance their experience, and in fact we’re aiming for mostly the same user experience across languages.

It’s a good suggestion. We have to deliberate a bit to figure out if we want to trade off a safer and slightly more verbose experience for NPM users for a uniform experience across all languages.

Those are all good points, and I’m not sure how to reconcile those two goals.