Contributing to create-awesome-node-app

1Extension Structure

An extension typically consists of files that will be added to or modified in a template. Here's a recommended structure:

extensions/
└── your-extension-name/
    ├── files/           # Files to be added to the template
    │   ├── src/         # Source files to be added
    │   └── ...          # Other files
    ├── dependencies.json # Dependencies to be added to package.json
    ├── scripts.json     # Scripts to be added to package.json
    └── README.md        # Extension documentation

2Adding Your Extension to templates.json

Each extension must be registered in the templates.json file:

{
  "extensions": [
    // ... existing extensions
    {
      "name": "Your Extension Name",
      "slug": "your-extension-name",
      "description": "A concise description of your extension",
      "url": "https://github.com/Create-Node-App/cna-templates/tree/main/extensions/your-extension-name",
      "type": ["template-type1", "template-type2"],
      "category": "Extension Category",
      "labels": ["Label1", "Label2", "Label3"]
    }
  ]
}

Here's what each property means:

• name: The display name of your extension
• slug: A unique identifier for your extension (URL-friendly)
• description: A brief description of what your extension offers
• url: The URL to your extension in the repository
• type: The type(s) of templates this extension is compatible with (string or array of strings)
• category: The category of the extension (e.g., "UI", "State Management", "Tooling")
• labels: Keywords that describe your extension

3Creating an Extension

Follow these steps to create a new extension:

1. Identify the need: Determine what functionality you want to add to existing templates.
2. Create the extension files: Prepare the files that will be added to or modified in the template.
3. Define dependencies: Create a dependencies.json file listing any npm packages your extension requires.
4. Add scripts: If your extension needs to add scripts to package.json, create a scripts.json file.
5. Document your extension: Create a README.md that explains how to use your extension and what it provides.

// Example dependencies.json
{
  "dependencies": {
    "axios": "^1.3.4",
    "react-query": "^3.39.3"
  },
  "devDependencies": {
    "@types/axios": "^0.14.0"
  }
}

// Example scripts.json
{
  "scripts": {
    "api:generate": "openapi-generator-cli generate -i api-spec.yaml -g typescript-axios -o src/api"
  }
}

4Ensuring Compatibility

Extensions must be compatible with the templates they're designed for. Here's how to ensure compatibility:

• Specify compatible template types: In your extension's entry in templates.json, list all compatible template types in the type property.
• Test with all compatible templates: Verify that your extension works correctly with all the template types you've specified.
• Handle template variations: If templates have different structures (e.g., with or without a src directory), make your extension adaptable.

// Example of specifying multiple compatible template types
"type": ["react", "nextjs", "webextension-react"]

5Submitting Your Extension

The process for submitting an extension is similar to submitting a template:

1. Fork the repository: Create a fork of the cna-templates repository on GitHub.
2. Add your extension: Place your extension in the extensions/ directory.
3. Update templates.json: Add your extension to the templates.json file as described above.
4. Create a pull request: Submit a pull request with a clear description of your extension.