misleading init templates and sample app

❓ General Issue

Our current init templates and sample app don’t really encourage the behavior and programming model we want customers to adopt.

The problem is this:

export class %name.PascalCased%Stack extends cdk.Stack {
  ...
  ...
}

The fact we are defaulting to extending cdk.Stack sets users in a trajectory to actually use Stacks as the sharable, reusable, component. In reality, these components should simply be regular constructs.

A Stack might encapsulate deployment context that isn’t really sharable or generic:

• Environment (account, region)
• Stack name
• availabilityZones
• …

It feels like our core Stack (similar to App) object should be used when defining the actual application that will be deployed (what we currently define in bin), and not the re-usable component (what we currently define in lib).

It follows, that stacks should probably only have one construct.

@eladb Did mention that Stacks can be used inside organizations to enforce specific policies related to deployment, but that probably shouldn’t be our main use-case.

As far as templates and examples go, we should have a distinction between customers who are merely construct users, and those who are construct authors.

For example, for users, perhaps a more natural and simplified version of the template could be:

index.ts

#!/usr/bin/env node
import 'source-map-support/register';
import * as cdk from '@aws-cdk/core';

const app = new cdk.App();
const stack = new cdk.Stack(app, 'MyStack');

// The code that defines your stack goes here

This structure is much simpler for customers who simply want to create a stack and deploy it.

For authors, which are more advanced customers, we can stick to our current template structure, but extending cdk.Construct instead of cdk.Stack.

export class %name.PascalCased%Construct extends cdk.Construct {
  ...
  ...
}

This distinction, between authors and users, is valid and exists in most programming languages and tools, with regards to best practices and such.

We should also probably create a some kind of best practices document, which will also detail when should you actually choose to extend Stack instead of Construct.

The Question

Thoughts?

Environment

• CDK CLI Version: ALL
• Module Version: ALL
• OS: ALL
• Language: ALL

[hoegertn]

I think the difference between users and authors is already there with the app template and the lib template, isn’t it?

I really like the current structure and it works well in several scenarios.

[eladb]

How about making this even simpler for the simple use case?

import { SingleStackApp } from '@aws-cdk/core';
import * as s3 from '@aws-cdk/aws-s3';

const app = new SingleStackApp();
new s3.Bucket(app, 'MyBucket');
app.synth();