@jttc/projen-project-types 1.0.0-beta.0 → 1.0.0-beta.2

package/docs/default-configurations.md

@@ -0,0 +1,267 @@
+# Default Configurations
+
+This document describes the default configurations applied to all project types in this package.
+
+## Prettier Configuration
+
+All projects include Prettier with the following default settings:
+
+### Settings Applied
+
+```json title=".prettierrc.json" linenums="1"
+{
+  "trailingComma": "es5",
+  "singleQuote": true,
+  "bracketSpacing": true,
+  "semi": true
+}
+```
+
+### Rationale
+
+- **`trailingComma: "es5"`**: Ensures consistent trailing commas in objects and arrays, making diffs cleaner
+- **`singleQuote: true`**: Uses single quotes for strings, which is common in JavaScript/TypeScript projects
+- **`bracketSpacing: true`**: Adds spaces inside object literal braces `{ foo: bar }`
+- **`semi: true`**: Always includes semicolons for statement termination
+
+### Customization
+
+You can override these settings by providing custom `prettierOptions`:
+
+```typescript title="Custom Prettier Configuration" linenums="1" hl_lines="5 6 7 8"
+const project = new ProjectType({
+  // ... other options
+  prettierOptions: {
+    settings: {
+      singleQuote: false,
+      semi: false,
+      tabWidth: 4,
+      printWidth: 120,
+    },
+  },
+});
+```
+
+**Highlighted lines explanation:**
+
+- **Line 5**: Use double quotes instead of single quotes
+- **Line 6**: Omit semicolons for cleaner code
+- **Line 7**: Use 4 spaces for indentation instead of 2
+- **Line 8**: Allow longer line length
+
+### Disabling Prettier
+
+To completely disable Prettier:
+
+```typescript title="Disable Prettier" linenums="1" hl_lines="3"
+const project = new ProjectType({
+  // ... other options
+  prettier: false,
+});
+```
+
+**Highlighted line explanation:**
+
+- **Line 3**: No `.prettierrc.json` file will be created
+
+## VSCode Configuration
+
+All projects include VSCode workspace configuration when enabled (default behavior).
+
+### Settings Applied
+
+```json title=".vscode/settings.json" linenums="1"
+{
+  "editor.formatOnSave": true,
+  "editor.indentSize": 2, 
+  "editor.defaultFormatter": "esbenp.prettier-vscode",
+  "eslint.nodePath": "./node_modules",
+  "eslint.useFlatConfig": false
+}
+```
+
+### Recommended Extensions
+
+The following extensions are automatically recommended for all projects:
+
+```json title=".vscode/extensions.json" linenums="1"
+{
+  "recommendations": [
+    "amazonwebservices.aws-toolkit-vscode",
+    "DanielThielking.aws-cloudformation-yaml", 
+    "ms-azuretools.vscode-containers",
+    "dbaeumer.vscode-eslint",
+    "esbenp.prettier-vscode",
+    "mhutchie.git-graph",
+    "github.vscode-github-actions",
+    "GitHub.vscode-pull-request-github",
+    "eamodio.gitlens",
+    "spmeesseman.vscode-taskexplorer",
+    "wayou.vscode-todo-highlight",
+    "vscode-icons-team.vscode-icons",
+    "ms-vscode-remote.vscode-remote-extensionpack"
+  ]
+}
+```
+
+#### Development Tools
+- **AWS Toolkit for VS Code** (`amazonwebservices.aws-toolkit-vscode`)
+- **CloudFormation YAML** (`DanielThielking.aws-cloudformation-yaml`)
+- **Docker** (`ms-azuretools.vscode-containers`)
+
+#### Code Quality & Formatting
+- **ESLint** (`dbaeumer.vscode-eslint`)
+- **Prettier** (`esbenp.prettier-vscode`)
+
+#### Git & Version Control
+- **Git Graph** (`mhutchie.git-graph`)
+- **GitHub Actions** (`github.vscode-github-actions`)
+- **GitHub Pull Requests** (`GitHub.vscode-pull-request-github`)
+- **GitLens** (`eamodio.gitlens`)
+
+#### Productivity
+- **Task Explorer** (`spmeesseman.vscode-taskexplorer`)
+- **TODO Highlight** (`wayou.vscode-todo-highlight`)
+- **VSCode Icons** (`vscode-icons-team.vscode-icons`)
+- **Remote Development Extension Pack** (`ms-vscode-remote.vscode-remote-extensionpack`)
+
+### Rationale
+
+- **Format on save**: Automatically formats code when saving, ensuring consistency
+- **Prettier as default formatter**: Uses the configured prettier settings
+- **ESLint integration**: Provides real-time linting and error detection
+- **AWS-focused extensions**: Optimized for AWS and cloud development workflows
+- **Git workflow tools**: Enhanced git management and collaboration features
+
+### Customization
+
+You can disable VSCode configuration entirely:
+
+```typescript
+const project = new ProjectType({
+  // ... other options
+  vscode: false,
+});
+```
+
+Currently, there's no built-in way to customize individual VSCode settings or extensions, but this may be added in future versions.
+
+## Configuration Behavior
+
+### Default Behavior (Recommended)
+
+When no explicit configuration is provided:
+
+```typescript title="Default Configuration" linenums="1"
+const project = new ProjectType({
+  name: 'my-project',
+  // ... other required options
+  // prettier: undefined (defaults to true)
+  // vscode: undefined (defaults to true)
+});
+```
+
+**Result**: Both Prettier and VSCode configurations are applied with default settings.
+
+### Mixed Configurations
+
+You can mix and match configurations:
+
+=== "Prettier Only"
+
+    ```typescript linenums="1" title="Prettier Only Configuration" hl_lines="3 4"
+    const project = new ProjectType({
+      // ... other options
+      prettier: true,
+      vscode: false,
+    });
+    ```
+
+    **Highlighted lines explanation:**
+    
+    - **Line 3**: Enable prettier with default settings
+    - **Line 4**: No VSCode configuration files created
+
+=== "VSCode Only"
+
+    ```typescript linenums="1" title="VSCode Only Configuration" hl_lines="3 4"
+    const project = new ProjectType({
+      // ... other options 
+      prettier: false,
+      vscode: true,
+    });
+    ```
+
+    **Highlighted lines explanation:**
+    
+    - **Line 3**: No prettier configuration files created
+    - **Line 4**: Enable VSCode with default settings
+
+=== "Both Disabled"
+
+    ```typescript linenums="1" title="Minimal Configuration" hl_lines="3 4"
+    const project = new ProjectType({
+      // ... other options
+      prettier: false,
+      vscode: false,
+    });
+    ```
+
+    **Highlighted lines explanation:**
+    
+    - **Line 3**: No prettier files
+    - **Line 4**: No VSCode files
+
+## Files Created
+
+### When Prettier is Enabled
+
+- `.prettierrc.json` - Prettier configuration file
+- `.prettierignore` - Files to ignore during formatting (if applicable)
+
+### When VSCode is Enabled
+
+- `.vscode/settings.json` - Workspace settings
+- `.vscode/extensions.json` - Recommended extensions
+
+## Best Practices
+
+### 1. Stick with Defaults
+
+The default configurations have been carefully chosen for optimal development experience across teams. Unless you have specific requirements, it's recommended to use the defaults.
+
+### 2. Team Consistency
+
+If you customize configurations, ensure all team members are aware of the changes and update their local environments accordingly.
+
+### 3. Document Customizations
+
+If you deviate from defaults, document the reasons in your project's README or contributing guidelines.
+
+### 4. Extension Installation
+
+Encourage team members to install the recommended VSCode extensions for the best development experience.
+
+## Future Enhancements
+
+Planned improvements to the default configurations:
+
+- **ESLint default configuration**: Common ESLint rules for TypeScript projects
+- **Jest configuration**: Default test setup and configuration
+- **GitHub Actions**: Standard CI/CD workflows
+- **Dependabot**: Automated dependency updates
+- **Customizable VSCode settings**: Allow overriding individual settings and extensions
+
+## Contributing
+
+To propose changes to the default configurations:
+
+1. Open an issue describing the proposed change and rationale
+2. Discuss with maintainers and community
+3. Submit a pull request with the changes
+4. Update documentation and tests
+5. Ensure backward compatibility
+
+---
+
+*These configurations are maintained by [Jump to the Cloud](https://jumptothecloud.tech) and are designed to provide productive development environments out of the box.*

package/docs/index.md

@@ -29,7 +29,26 @@ While projen provides excellent base project types, real-world projects often re
 
 ## Getting Started
 
-More detailed documentation and project types will be added as features are developed. Stay tuned for updates!
+Choose from our available project types:
+
+### 🏗️ [CDK Library Project](project-types/cdk-library.md)
+
+Create AWS CDK construct libraries with opinionated configurations:
+
+- Pre-configured Prettier settings
+- VSCode workspace setup with recommended extensions
+- Best practices for CDK library development
+- Fully customizable while maintaining sensible defaults
+
+```bash linenums="1" title="Create new CDK Library project"
+# Create a new CDK Library project
+npx projen new --from @jttc/projen-project-types cdk-library
+```
+
+!!! tip "Getting Started"
+    After running the command above, follow the interactive prompts to configure your project, then customize further by editing `.projenrc.ts`
+
+More project types are planned for future releases!
 
 ## Contributing
 

package/docs/project-types/cdk-library.md

@@ -0,0 +1,413 @@
+# CDK Library Project
+
+The CDK Library Project type provides an opinionated setup for creating AWS CDK construct libraries with best practices and common configurations pre-configured.
+
+## Overview
+
+This project type extends the standard `AwsCdkConstructLibrary` from projen with additional features:
+
+- **Prettier configuration** with sensible defaults
+- **VSCode settings and extensions** for enhanced development experience  
+- **Common project structure** and tooling setup
+- **Configurable options** that respect user preferences
+
+## Quick Start
+
+To create a new CDK Library project, use the projen CLI:
+
+```bash linenums="1"
+npx projen new --from @jttc/projen-project-types cdk-library
+```
+
+This command will create a new project with the CDK Library template and prompt you for the required configuration options such as:
+
+- Project name
+- Author information
+- Repository URL
+- CDK version
+- Default branch
+
+After the project is created, you can customize it further by editing the `.projenrc.ts` file:
+
+```typescript linenums="1" title=".projenrc.ts" hl_lines="4 8 12 13"
+import { CdkLibrary } from '@jttc/projen-project-types';
+
+const project = new CdkLibrary({
+  name: 'my-awesome-cdk-library',
+  author: 'Your Name',
+  authorAddress: 'your.email@example.com',
+  repositoryUrl: 'https://github.com/yourusername/my-awesome-cdk-library.git',
+  cdkVersion: '2.1.0',
+  defaultReleaseBranch: 'main',
+  
+  // Add any additional customizations here
+  prettier: true,
+  vscode: true,
+});
+
+project.synth();
+```
+
+**Highlighted lines explanation:**
+
+- **Line 4**: Choose a descriptive name for your CDK construct library
+- **Line 8**: Pin to a specific CDK version for consistency
+- **Line 12**: Enable prettier formatting (default: true)
+- **Line 13**: Enable VSCode workspace configuration (default: true)
+
+## Features
+
+### Automatic Prettier Configuration
+
+The CDK Library project automatically configures Prettier with opinionated settings. For detailed information about the default prettier configuration used across all project types, see [Default Configurations](../default-configurations.md#prettier-configuration).
+
+#### Summary of Default Settings
+
+- **Single quotes** for strings
+- **Trailing commas** (ES5 style) 
+- **Bracket spacing** enabled
+- **Semicolons** required
+
+!!! tip "View Complete Configuration"
+    See the [Default Configurations](../default-configurations.md#prettier-configuration) page for the complete prettier setup and customization options.
+
+### VSCode Integration
+
+When enabled, the project automatically sets up VSCode configuration with settings and recommended extensions optimized for CDK development. For complete details about VSCode configuration, see [Default Configurations](../default-configurations.md#vscode-configuration).
+
+#### Key Features
+
+- Format on save enabled
+- Prettier as default formatter
+- ESLint integration
+- AWS and Git development extensions
+- Proper indentation and editor settings
+
+## Configuration Options
+
+### Basic Configuration
+
+All standard `AwsCdkConstructLibraryOptions` are supported. Here are the required options:
+
+```typescript linenums="1" title="Basic CDK Library Configuration"
+const project = new CdkLibrary({
+  // Required options
+  name: 'my-cdk-library',
+  author: 'Your Name',
+  authorAddress: 'your.email@example.com', 
+  repositoryUrl: 'https://github.com/yourusername/my-cdk-library.git',
+  cdkVersion: '2.1.0',
+  defaultReleaseBranch: 'main',
+  
+  // Optional configurations (see sections below)
+});
+```
+
+### Prettier Configuration
+
+#### Enable/Disable Prettier
+
+```typescript linenums="1" title="Disable Prettier" hl_lines="3"
+const project = new CdkLibrary({
+  // ... other options
+  prettier: false,
+});
+```
+
+**Highlighted line explanation:**
+
+- **Line 3**: Disables prettier entirely - no `.prettierrc.json` file will be created
+
+#### Custom Prettier Options
+
+```typescript linenums="1" title="Custom Prettier Configuration" hl_lines="5 6 7 8 9"
+const project = new CdkLibrary({
+  // ... other options
+  prettier: true,
+  prettierOptions: {
+    settings: {
+      singleQuote: false,
+      semi: false,
+      tabWidth: 4,
+      trailingComma: 'none',
+      printWidth: 120,
+    },
+  },
+});
+```
+
+**Highlighted lines explanation:**
+
+- **Line 6**: Use double quotes instead of single quotes
+- **Line 7**: Omit semicolons
+- **Line 8**: Use 4 spaces for indentation instead of 2
+- **Line 9**: No trailing commas
+- **Line 10**: Allow longer lines (120 characters instead of 80)
+
+### VSCode Configuration
+
+#### Enable/Disable VSCode Setup
+
+=== "Default Behavior (Recommended)"
+
+    ```typescript linenums="1" title="VSCode Enabled by Default"
+    const project = new CdkLibrary({
+      // ... other options
+      // vscode: undefined (defaults to enabled)
+    });
+    ```
+
+=== "Explicitly Enable"
+
+    ```typescript linenums="1" title="Explicitly Enable VSCode" hl_lines="3"
+    const project = new CdkLibrary({
+      // ... other options
+      vscode: true,
+    });
+    ```
+
+    **Highlighted line explanation:**
+    
+    - **Line 3**: Same as default behavior, but explicit
+
+=== "Disable VSCode"
+
+    ```typescript linenums="1" title="Disable VSCode Configuration" hl_lines="3"
+    const project = new CdkLibrary({
+      // ... other options
+      vscode: false,
+    });
+    ```
+
+    **Highlighted line explanation:**
+    
+    - **Line 3**: No `.vscode/` folder will be created
+
+### Behavior Matrix
+
+| `prettier` | `vscode` | Prettier Files | VSCode Files | Description |
+|------------|----------|----------------|--------------|-------------|
+| `undefined` | `undefined` | ✅ Created | ✅ Created | Default behavior - both enabled |
+| `true` | `true` | ✅ Created | ✅ Created | Explicitly enabled |
+| `false` | `true` | ❌ Not created | ✅ Created | Only VSCode enabled |
+| `true` | `false` | ✅ Created | ❌ Not created | Only Prettier enabled |
+| `false` | `false` | ❌ Not created | ❌ Not created | Both disabled |
+
+## Examples
+
+### Minimal Setup
+
+Perfect for getting started quickly with all defaults:
+
+```typescript linenums="1" title=".projenrc.ts - Minimal Setup"
+import { CdkLibrary } from '@jttc/projen-project-types';
+
+const project = new CdkLibrary({
+  name: 'simple-cdk-library',
+  author: 'John Doe',
+  authorAddress: 'john@example.com',
+  repositoryUrl: 'https://github.com/johndoe/simple-cdk-library.git',
+  cdkVersion: '2.1.0',
+  defaultReleaseBranch: 'main',
+  // All other options use sensible defaults
+});
+
+project.synth();
+```
+
+### Customized Setup
+
+Example with custom prettier settings and additional CDK options:
+
+```typescript linenums="1" title=".projenrc.ts - Advanced Configuration" hl_lines="11 12 18 19 20"
+import { CdkLibrary } from '@jttc/projen-project-types';
+
+const project = new CdkLibrary({
+  name: 'advanced-cdk-library',
+  author: 'Jane Smith',
+  authorAddress: 'jane@company.com',
+  repositoryUrl: 'https://github.com/company/advanced-cdk-library.git',
+  cdkVersion: '2.1.0',
+  defaultReleaseBranch: 'main',
+  
+  // Custom prettier settings
+  prettierOptions: {
+    settings: {
+      printWidth: 120,
+      tabWidth: 4,
+    },
+  },
+  
+  // Enable VSCode (explicit)
+  vscode: true,
+  
+  // Additional CDK library options
+  description: 'An advanced CDK construct library',
+  keywords: ['aws', 'cdk', 'constructs'],
+  license: 'MIT',
+});
+
+project.synth();
+```
+
+**Highlighted lines explanation:**
+
+- **Lines 11-16**: Custom prettier settings for longer lines and 4-space indentation
+- **Line 19**: Enable VSCode configuration explicitly
+- **Lines 22-24**: Additional NPM package metadata for discoverability
+
+### Development-Only Setup
+
+Optimized for local development with minimal tooling:
+
+```typescript linenums="1" title=".projenrc.ts - Development Focus" hl_lines="11 12"
+import { CdkLibrary } from '@jttc/projen-project-types';
+
+const project = new CdkLibrary({
+  name: 'dev-cdk-library',
+  author: 'Developer',
+  authorAddress: 'dev@localhost.com', 
+  repositoryUrl: 'https://github.com/dev/dev-cdk-library.git',
+  cdkVersion: '2.1.0',
+  defaultReleaseBranch: 'main',
+  
+  prettier: false,
+  vscode: true,
+});
+
+project.synth();
+```
+
+**Highlighted lines explanation:**
+
+- **Line 11**: Skip prettier for faster development iterations
+- **Line 12**: Keep VSCode config for better developer experience
+
+## Project Structure
+
+After running `yarn projen` with a CDK Library project, you'll get the following structure:
+
+```text title="Generated Project Structure"
+my-cdk-library/
+├── .github/
+│   └── workflows/              # CI/CD workflows
+│       ├── build.yml
+│       ├── release.yml
+│       └── upgrade-main.yml
+├── .vscode/                    # VSCode configuration (if enabled)
+│   ├── extensions.json         # Recommended extensions
+│   └── settings.json          # Editor settings
+├── src/
+│   └── index.ts               # Main library entry point
+├── test/
+│   └── *.test.ts              # Test files
+├── .eslintrc.json             # ESLint configuration
+├── .gitignore                 # Git ignore rules
+├── .prettierrc.json           # Prettier config (if enabled)
+├── .projenrc.ts              # Projen configuration
+├── package.json              # NPM package configuration
+├── tsconfig.json             # TypeScript configuration
+└── README.md                 # Generated README
+```
+
+!!! info "Conditional Files"
+    Some files are only created based on your configuration:
+    
+    - `.vscode/` folder: Only when `vscode: true` (default)
+    - `.prettierrc.json`: Only when `prettier: true` (default)
+
+## Best Practices
+
+### 1. Use Consistent Configurations
+
+Stick with the default prettier and VSCode configurations unless you have specific requirements. This ensures consistency across your team and projects.
+
+### 2. Leverage VSCode Extensions
+
+The recommended extensions provide significant productivity improvements for CDK development. Make sure your team installs them.
+
+### 3. Customize Thoughtfully
+
+While customization is available, consider whether deviating from defaults provides real value. Consistency often trumps personal preferences in team environments.
+
+### 4. Version Lock Your CDK Version
+
+Always specify a specific CDK version to ensure consistent builds across environments:
+
+```typescript
+cdkVersion: '2.1.0', // Good - specific version
+// cdkVersion: '^2.0.0', // Avoid - could lead to inconsistencies
+```
+
+## Troubleshooting
+
+### Prettier Not Working
+
+If prettier isn't formatting your code:
+
+1. Ensure the prettier extension is installed in VSCode
+2. Check that `"editor.defaultFormatter": "esbenp.prettier-vscode"` is in your VSCode settings
+3. Verify `.prettierrc.json` exists in your project root
+
+### VSCode Extensions Not Recommended
+
+If VSCode isn't showing extension recommendations:
+
+1. Check that `.vscode/extensions.json` exists
+2. Restart VSCode
+3. Go to Extensions panel and look for the "Recommended" section
+
+### Build Errors
+
+If you encounter build errors after setup:
+
+1. Run `yarn install` to ensure all dependencies are installed
+2. Run `yarn projen` to regenerate configuration files
+3. Check that your CDK version is compatible with your constructs version
+
+## Migration Guide
+
+### From Standard AwsCdkConstructLibrary
+
+To migrate from a standard `AwsCdkConstructLibrary` to `CdkLibrary`:
+
+1. Install the package: `npm install @jttc/projen-project-types`
+2. Update your `.projenrc.ts`:
+
+```diff
+- import { AwsCdkConstructLibrary } from 'projen/lib/awscdk';
++ import { CdkLibrary } from '@jttc/projen-project-types';
+
+- const project = new AwsCdkConstructLibrary({
++ const project = new CdkLibrary({
+  // ... same options
+});
+```
+
+3. Run `yarn projen` to regenerate files
+4. Commit the changes
+
+The migration is backward compatible - all existing options will continue to work.
+
+## Contributing
+
+To contribute improvements to the CDK Library project type:
+
+1. Fork the repository
+2. Make your changes
+3. Add tests for new functionality
+4. Update documentation
+5. Submit a pull request
+
+## Support
+
+If you encounter issues or have questions:
+
+- Check this documentation
+- Review existing GitHub issues
+- Create a new issue with detailed information
+- Tag the maintainers for urgent issues
+
+---
+
+*This project type is maintained by [Jump to the Cloud](https://jumptothecloud.tech) team.*