Document how to use components with local packages

[jkodroff]

Fixes #16173

Added documentation explaining how to properly configure components that contain local packages (such as Terraform providers via terraform-provider or nested components). This ensures users understand the requirement to commit generated SDK code to version control for Pulumi 3.200.0+.

Changes:

• Added new section "Using components with local packages" to local-packages.md explaining requirements and workflow
• Added warning note to build-a-component.md linking to detailed documentation
• Fixed command syntax for pulumi package add (removed --version flag)

🤖 Generated with Claude Code

[jkodroff]

Blocking on review from @julienp since we have to make sure the information is factually correct.

[claude]

Documentation Review

I've reviewed the changes in this PR. Overall, this is a valuable addition that addresses issue #16173 by documenting how to properly configure components with local packages. However, there are several issues that need to be fixed:

Issues Found

1. Incorrect shortcode syntax (build-a-component.md:44-46)

The warning note uses {{< notes >}} (angle brackets) but should use {{% notes %}} (percent signs) based on the STYLE-GUIDE.md example and Hugo's conventions for shortcodes that process markdown content.

Current:

{{< notes type="warning" >}}
If your component uses a local package...
{{< /notes >}}

Should be:

{{% notes type="warning" %}}
If your component uses a local package (such as any Terraform provider via `terraform-provider`, or another component that contains a local package), you must commit the generated SDK code to version control. See [Using components with local packages](/docs/iac/guides/building-extending/packages/local-packages/#components-with-local-packages) for details.
{{% /notes %}}

2. Inconsistent command examples (local-packages.md:209 and 238)

The command examples at line 209 and 238 show:

pulumi package add terraform-provider hashicorp/random 3.5.1

However, earlier in the same file (line 72), the command is shown without a version number:

pulumi package add terraform-provider hashicorp/random

For consistency and clarity, all examples should follow the same pattern. Since the "Versioning considerations" section (line 199-212) emphasizes the importance of pinning versions, it would be better to consistently show version numbers in all examples throughout the document.

3. Style: Avoid judging difficulty (local-packages.md:222-226)

The "Requirements" section uses simple numbered steps (1, 2, 3) which is good, but the content should be reviewed for clarity.

Line 224: "You must be using Pulumi 3.200.0 or later."

Consider rephrasing to be more specific about why this version is required, or if this is a hard requirement that will cause failures in earlier versions.

4. Minor: Repeated reference pattern (local-packages.md:218-220)

The bulleted list is clear, but the third item "Any other dynamically generated SDK" is somewhat vague. Consider providing a specific example or removing it if there are no other common cases besides Terraform providers and nested components.

Positive Aspects

• The new section is well-structured with clear subsections (Requirements, Why this is necessary, Example workflow)
• The anchor link #components-with-local-packages is properly defined
• Internal links are correctly formatted
• The command syntax fix (removing --version flag) at line 209 is correct
• The explanation of why SDK code must be committed is clear and helpful

Recommendations

1. Fix the shortcode syntax in build-a-component.md
2. Consider adding version numbers to all pulumi package add terraform-provider examples for consistency
3. Verify the shortcode renders correctly after making the syntax change

---

Mention me (@claude) if you'd like me to review the updated changes or help with any fixes.

[pulumi-bot]

Your site preview for commit 53745ef is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-16372-53745efb.s3-website.us-west-2.amazonaws.com.

[pulumi-bot]

Your site preview for commit e762b99 is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-16372-e762b99d.s3-website.us-west-2.amazonaws.com.

[julienp]

Seems to be a 404, I think it's meant to be this:

Suggested change

	Refer to the [Any Terraform Provider documentation](/docs/iac/using-pulumi/pulumi-packages/terraform-provider/) for more details.
	Refer to the [Any Terraform Provider documentation](/docs/iac/guides/building-extending/using-existing-tools/use-terraform-module/) for more details.

[julienp]

Very nice to have a "Why this is necessary" section 😍

[pulumi-bot]

Your site preview for commit 9b03bd3 is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-16372-9b03bd37.s3-website.us-west-2.amazonaws.com.