What is a Pulumi ComponentResource, and what must a ComponentResource subclass do in its constructor for the component to behave correctly?

## The problem it solves A plain function that creates five resources and returns some of them works fine — until you want the five to be treated as a unit. Pulumi's resource model is a tree, and a function creates no node in it. `ComponentResource` is the class you subclass to create that node. What you get from being a real node: the resources are nested under one URN in `pulumi stack` output and in the Pulumi Cloud resource view; deletion and options propagate down the parent chain; and the component can be published as a normal package in your language's ecosystem for others to `new` up. This last part is the substantive difference from a Terraform module, which is a directory of files consumed by a source address — a Pulumi component is a class, versioned and distributed like any other library code. ## The three constructor obligations ```typescript export class StaticSite extends pulumi.ComponentResource { public readonly bucketName: pulumi.Output<string>; constructor(name: string, args: { indexDocument: string }, opts?: pulumi.ComponentResourceOptions) { super("mycorp:web:StaticSite", name, {}, opts); const bucket = new aws.s3.Bucket(`${name}-bucket`, { website: { indexDocument: args.indexDocument }, }, { parent: this }); this.bucketName = bucket.bucket; this.registerOutputs({ bucketName: this.bucketName }); } } ``` **1. `super(type, name, props, opts)`.** The type token is a three-part string, conventionally `package:module:Type`. It is not decorative — it becomes part of every child's URN and is how the engine identifies the component's kind. Pick it once and do not change it casually, since changing it changes URNs. Passing `opts` through is what lets a caller set a parent, a provider or an alias on the component. **2. `{ parent: this }` on every child.** This is the obligation people forget. Without it, the children register at the stack root, and: - The tree is flat, so nothing visually or structurally connects them to the component. - Options that propagate down the parent chain — the provider, resource transformations, `protect` — do not reach them. - Child URNs are not scoped by the component, so two instances of the component can collide on names unless you manually prefix every one. Prefixing child names with the component's `name` argument, as above, is the standard convention that keeps two instances distinct in a readable way. **3. `this.registerOutputs({...})`.** Call it last. It tells the engine the component is done constructing and records the component's output properties. Omitting it is not always fatal but leaves the component's outputs unrecorded and the engine without a completion signal; treat it as mandatory. ## Exposing outputs A component's public surface is ordinary class fields typed as `Output<T>`. Callers consume them exactly as they would a real resource's attributes — pass them into other resources' args, apply over them, export them from the stack. That is a genuine ergonomic gain over a module system where the interface is a separate declaration file: the type checker enforces the interface, your editor autocompletes it, and a wrong field is a compile error rather than a plan-time one. ## ComponentResourceOptions vs CustomResourceOptions A child resource created by a provider takes `CustomResourceOptions`. A component takes `ComponentResourceOptions`, which adds `providers` — a map letting a caller supply, say, a specific AWS provider for everything inside the component. The distinction matters when you write the constructor signature: type it as `ComponentResourceOptions` so callers can pass a provider set down. ## When not to reach for one A component is worth the ceremony when the group has a real identity — a service, a network, a site. For a two-line helper that computes a tag map or builds an ARN, a plain function is better: no URN, no tree node, nothing to alias later. Over-componentising has a real cost, because every component boundary is a set of URNs you must migrate with aliases if you later change your mind about the structure. ## Remote components, briefly Components written in one language can be packaged as *multi-language* components so a Python program can consume a component authored in TypeScript. That is a packaging concern layered on the same class; the constructor obligations above are unchanged.