Add comprehensive project layout best practices by joeduffy · Pull Request #17006 · pulumi/docs

joeduffy · 2026-01-12T02:00:54Z

Expands the "Organizing your project code" section with practical guidance:

Common project structures (flat, by layer, by service)
When to use each approach
Pulumi-specific tips for config helpers and naming conventions
How to organize application code alongside infrastructure
When to split into separate projects

This gives users concrete examples rather than just abstract concepts.

Expands the "Organizing your project code" section with practical guidance: - Common project structures (flat, by layer, by service) - When to use each approach - Pulumi-specific tips for config helpers and naming conventions - How to organize application code alongside infrastructure - When to split into separate projects This gives users concrete examples rather than just abstract concepts. Fixes #11766 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

claude · 2026-01-12T02:04:39Z

Documentation Review

This PR significantly expands the "Organizing your project code" section with practical, actionable guidance. The content is well-structured and provides valuable real-world examples. However, there are a few issues to address:

Issues Found

1. Typographical inconsistency (line 331)

The text uses "Typescript" but should be "TypeScript" (capital S) for consistency with the official TypeScript branding and the rest of the documentation.

Organize your code in a way that makes it easy to understand and maintain. One way to do this in TypeScript is to break out your code into separate files, and then import them into your main file. In this example, the entrypoint for our Pulumi program is `index.ts`, but we use the `utils.ts` file for supporting functions.

2. Consider adding a trailing newline verification

While I cannot confirm from the diff whether the file ends with a newline (as required by AGENTS.md), please verify that the file ends with a proper trailing newline character.

Strengths

Clear structure: The hierarchical organization (flat → by layer → by service) provides an effective learning progression
Practical examples: The directory tree diagrams and code snippets give concrete guidance
Good decision guidance: "When to use" sections help readers choose appropriate patterns
Pulumi-specific tips: The configuration helpers and naming conventions sections add real value
Appropriate cross-references: The stack references link is well-placed

Style Compliance

✅ Headings follow sentence case (H2+)
✅ No directional language ("above," "below")
✅ Consistent terminology
✅ Clear, concise paragraphs
✅ Code examples are realistic and follow best practices
✅ Internal links use proper Markdown syntax

Overall, this is a strong enhancement that addresses issue #11766 effectively. Once the TypeScript capitalization is corrected, this will be ready to merge.

Mention me (@claude) if you'd like me to review any updates or have questions!

pulumi-bot · 2026-01-12T02:07:32Z

Your site preview for commit 22e1c06 is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-17006-22e1c066.s3-website.us-west-2.amazonaws.com.

cnunciato

A few things we might want to tweak here, but this extra detail definitely helps!

cnunciato · 2026-01-12T22:15:48Z

+// Validate config at program start
+if (!["dev", "staging", "prod"].includes(environment)) {
+    throw new Error(`Unknown environment: ${environment}`);
+}


Is this (hard-coding "allowed" stack names) a common pattern? I haven't seen it much myself — but if it's something we think is a best practice, or that we see in the wild, I'd be okay with it. Otherwise, might suggest we nix, or replace with something more common (reading another file, from ENV, from an async service, etc.).

This particular example would also benefit slightly from a usage example. (It'd be simple, but complete the picture a bit better.) Happy to add one if you like!

@jkodroff is this something we ever see in the wild?

This is just not a good practice IMO. The environment name is usually synonymous with the stack name, and to me, by virtue of a stack being initialized, it's valid, not something we need to validate after the fact.

cnunciato · 2026-01-12T22:41:45Z

+export function name(resourceName: string): string {
+    return `${project}-${stack}-${resourceName}`;
+}
+```


This one could also benefit from a usage example (again, simple, but would make the usefulness clearer IMO).

I don't think this is needed at all with latest and greatest autonaming.

…ex.md Co-authored-by: Christian Nunciato <c@nunciato.org>

pulumi-bot · 2026-01-13T01:02:07Z

Your site preview for commit 98e468e is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-17006-98e468e6.s3-website.us-west-2.amazonaws.com.

pulumi-bot · 2026-01-13T01:02:29Z

Your site preview for commit 328cdbd is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-17006-328cdbd3.s3-website.us-west-2.amazonaws.com.

pulumi-bot · 2026-01-13T01:03:10Z

Your site preview for commit a0073f6 is ready! 🎉

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

pulumi-bot · 2026-01-13T01:03:32Z

Your site preview for commit 322ba21 is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-17006-322ba218.s3-website.us-west-2.amazonaws.com.

pulumi-bot · 2026-01-13T01:03:49Z

Your site preview for commit 7c0f740 is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-17006-7c0f7406.s3-website.us-west-2.amazonaws.com.

jkodroff

Since this is such foundational guidance, I think we need to go over this with a fine-toothed comb and make sure there's consensus. I'm not quite at the "Request Changes" level since this probably makes things better, but I think we would do better to vet this a little more before shipping.

jkodroff · 2026-01-13T15:37:58Z

+
+#### Organized by resource layer
+
+For medium-sized projects, organize files by infrastructure layer:


I disagree on this. I would keep all resources in the entrypoint file, except for (local) components, which nearly always go in a separate file. If there's a local library or maybe structured config classes, those would also each go in a separate file.

If you have that many resources that you need to split among that many files, you should probably have separate programs, e.g the classic Networking -> K8s Cluster -> Workloads pattern of codebases.

jkodroff · 2026-01-13T15:38:19Z

+├── Pulumi.dev.yaml
+├── Pulumi.prod.yaml
+├── index.ts          # Main entrypoint
+└── config.ts         # Config helpers and constants


Usually not necessary IMO.

jkodroff · 2026-01-13T15:39:29Z

+├── Pulumi.yaml
+├── Pulumi.dev.yaml
+├── Pulumi.prod.yaml
+├── index.ts              # Main entrypoint


Without giving an outline of what the entrypoint file contains, this example risks confusing more than it clarifies.

jkodroff · 2026-01-13T15:41:46Z

+}
+```
+
+**Application code alongside infrastructure:** If your Pulumi project also contains application code (such as Lambda function code or Docker build contexts), consider organizing it into clearly labeled directories:


This example is the most useful yet, but it's specific to a serverless app IMO.

We should also show a containerized version, which for me would do something like:

README.md Makefile # or whatever - orchestrates building the app code, deploying to a container registry, and then calling Pulumi to deploy app/ (app code here) infra/ (Pulumi code here)

Based on review feedback from jkodroff and cnunciato: - Remove environment validation example (conflicts with stack-based environments) - Remove resource naming conventions helper (modern autonaming makes this unnecessary) - Revise file organization guidance to emphasize keeping resources in entrypoint - Add guidance to split into multiple projects if complexity grows - Soften config.ts guidance from prescriptive to optional - Add containerized application example with Makefile pattern - Convert bold headers to proper subheadings for better structure These changes make the guidance more conservative and aligned with current best practices. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

CamSoper · 2026-01-29T22:25:01Z

@jkodroff I've addressed your feedback from the review:

Removed environment validation example - Agreed this isn't a best practice and conflicts with stack-based environments
Removed naming conventions helper - Modern autonaming makes this unnecessary
Revised file organization guidance - Now emphasizes keeping resources in entrypoint, with separate files primarily for components/libraries. Added guidance to split into multiple projects if complexity grows
Softened config.ts guidance - Changed from prescriptive to optional
Enhanced service/feature example - Added context about what entrypoint contains
Added containerized example - Included the Makefile pattern you suggested alongside the serverless example
Fixed formatting - Changed bold headers to proper subheadings per @cnunciato's feedback

The revised guidance is more conservative and aligned with current best practices. A few questions:

Is there more work you'd like to see on this before it ships?
Do you think this content is valuable to merge now, or should we backburner it for more team discussion?

pulumi-bot · 2026-01-29T22:34:58Z

Your site preview for commit 4776f62 is ready! 🎉

http://www-testing-pulumi-docs-origin-pr-17006-4776f627.s3-website.us-west-2.amazonaws.com.

* Add comprehensive project layout best practices Expands the "Organizing your project code" section with practical guidance: - Common project structures (flat, by layer, by service) - When to use each approach - Pulumi-specific tips for config helpers and naming conventions - How to organize application code alongside infrastructure - When to split into separate projects This gives users concrete examples rather than just abstract concepts. Fixes #11766 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * Update content/docs/iac/guides/basics/organizing-projects-stacks/_index.md Co-authored-by: Christian Nunciato <c@nunciato.org> * Update content/docs/iac/guides/basics/organizing-projects-stacks/_index.md Co-authored-by: Christian Nunciato <c@nunciato.org> * Update content/docs/iac/guides/basics/organizing-projects-stacks/_index.md Co-authored-by: Christian Nunciato <c@nunciato.org> * Update content/docs/iac/guides/basics/organizing-projects-stacks/_index.md Co-authored-by: Christian Nunciato <c@nunciato.org> * Update content/docs/iac/guides/basics/organizing-projects-stacks/_index.md Co-authored-by: Christian Nunciato <c@nunciato.org> * Address PR feedback on project organization guidance Based on review feedback from jkodroff and cnunciato: - Remove environment validation example (conflicts with stack-based environments) - Remove resource naming conventions helper (modern autonaming makes this unnecessary) - Revise file organization guidance to emphasize keeping resources in entrypoint - Add guidance to split into multiple projects if complexity grows - Soften config.ts guidance from prescriptive to optional - Add containerized application example with Makefile pattern - Convert bold headers to proper subheadings for better structure These changes make the guidance more conservative and aligned with current best practices. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com> Co-authored-by: Cam Soper <csoper@pulumi.com> Co-authored-by: Christian Nunciato <c@nunciato.org> Co-authored-by: Cam <cam.soper@outlook.com>

joeduffy requested review from CamSoper and cnunciato January 12, 2026 02:00

joeduffy temporarily deployed to testing January 12, 2026 02:00 — with GitHub Actions Inactive

cnunciato reviewed Jan 12, 2026

View reviewed changes

Update content/docs/iac/guides/basics/organizing-projects-stacks/_ind…

a0073f6

…ex.md Co-authored-by: Christian Nunciato <c@nunciato.org>

CamSoper temporarily deployed to testing January 13, 2026 00:55 — with GitHub Actions Inactive

Update content/docs/iac/guides/basics/organizing-projects-stacks/_ind…

98e468e

…ex.md Co-authored-by: Christian Nunciato <c@nunciato.org>

CamSoper temporarily deployed to testing January 13, 2026 00:55 — with GitHub Actions Inactive

Update content/docs/iac/guides/basics/organizing-projects-stacks/_ind…

322ba21

…ex.md Co-authored-by: Christian Nunciato <c@nunciato.org>

CamSoper temporarily deployed to testing January 13, 2026 00:55 — with GitHub Actions Inactive

Update content/docs/iac/guides/basics/organizing-projects-stacks/_ind…

328cdbd

…ex.md Co-authored-by: Christian Nunciato <c@nunciato.org>

CamSoper temporarily deployed to testing January 13, 2026 00:56 — with GitHub Actions Inactive

Update content/docs/iac/guides/basics/organizing-projects-stacks/_ind…

7c0f740

…ex.md Co-authored-by: Christian Nunciato <c@nunciato.org>

CamSoper temporarily deployed to testing January 13, 2026 00:56 — with GitHub Actions Inactive

jkodroff reviewed Jan 13, 2026

View reviewed changes

CamSoper self-assigned this Jan 29, 2026

CamSoper temporarily deployed to testing January 29, 2026 22:24 — with GitHub Actions Inactive

jkodroff approved these changes Jan 30, 2026

View reviewed changes

CamSoper merged commit 63750aa into master Jan 30, 2026
12 checks passed

CamSoper deleted the joeduffy/fix-issue-11766-project-layout branch January 30, 2026 19:29

CamSoper temporarily deployed to testing January 30, 2026 19:29 — with GitHub Actions Inactive


		#### Organized by resource layer

		For medium-sized projects, organize files by infrastructure layer:

Conversation

joeduffy commented Jan 12, 2026

Uh oh!

claude Bot commented Jan 12, 2026

Documentation Review

Issues Found

Strengths

Style Compliance

Uh oh!

pulumi-bot commented Jan 12, 2026

Uh oh!

cnunciato left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

pulumi-bot commented Jan 13, 2026

Uh oh!

pulumi-bot commented Jan 13, 2026

Uh oh!

pulumi-bot commented Jan 13, 2026

Uh oh!

pulumi-bot commented Jan 13, 2026

Uh oh!

pulumi-bot commented Jan 13, 2026

Uh oh!

jkodroff left a comment

Choose a reason for hiding this comment

Uh oh!

jkodroff Jan 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

CamSoper commented Jan 29, 2026

Uh oh!

pulumi-bot commented Jan 29, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

jkodroff Jan 13, 2026 •

edited

Loading