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

[davidbarsky]

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.

[rix0rrr]

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

?

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

{
  "scripts": {
    "cdk": "cdk"
  },
  "devDependencies": {
     "aws-cdk": "^0.10.0"
  } 
}

In it?

[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.

[rix0rrr]

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.

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.

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.

[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.

[ericdmoore]

Maybe check out Storybook ¹ too to see how they leverage the npx² command for installation and issuing commands to the CLI tools. It also gets you started in an existing project without having installed anything globally. Python has largely standardized on some flavor of virtual env via venv or pyenv - java

Link Reference:
1: Storybook Example
2: NPX reference

[nmussy]

Is there still interest in this? Creating a @aws-cdk/create-deploy package would enable the use of:

• npm init @aws-cdk/deploy (see docs)
• yarn create @aws-cdk/deploy (see docs and blog)

Implementation-wise, it could simply alias cdk init. As for usage after init, as previously mentioned, npx cdk deploy and yarn cdk deploy would continue working.

[rix0rrr]

I believe we do this now, closing this issue.