Draft: custom-elements.json removed from .gitignore

[tshimber]

Fixes #2302

[netlify]

✅ Deploy Preview for marvelous-moxie-a6e2fe ready!

Name	Link
🔨 Latest commit	7281a62
🔍 Latest deploy log	https://app.netlify.com/sites/marvelous-moxie-a6e2fe/deploys/66d58f3c21b53500085ef219
😎 Deploy Preview	https://deploy-preview-2347--marvelous-moxie-a6e2fe.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[tshimber]

Some comments from ChatGPT:

The custom-elements.json file is updated automatically each time you build or rebuild your project. This file is created and updated during the compilation process when Stencil analyzes your components and generates metadata necessary to describe the custom elements.

Key moments when custom-elements.json is updated:

• When running the build command: Every time you run the npm run build or stencil build command, Stencil compiles the project and updates the custom-elements.json file with up-to-date information about the components.
• When working in watch mode: If you use the stencil build --watch command or npm start, Stencil monitors changes in the code and automatically rebuilds the project. Whenever the project is rebuilt, the custom-elements.json file is also updated.

This file is important for integration with other tools and frameworks, such as Storybook or documentation, and contains information about all registered components, their properties, events, and methods.

[tshimber]

The custom-elements.json file should typically be included in the final build of a Stencil component library that is distributed via npm and ends up in the node_modules directory when installed.

custom-elements.json should be at the same level as package.json, not buried deep within the dist/ folder or other directories. This placement ensures that tools and developers can easily access the file when needed.

Including custom-elements.json in the final package helps:

• Tooling: Tools like Storybook or integrated documentation systems can automatically pick up the component metadata.
• Framework Integration: Frameworks that use this metadata to provide enhanced support for web components (e.g., Angular, React wrappers) can function correctly.
• Documentation: Consumers of the library can understand the API of the components without needing to dig into the source code.

[tshimber]

The custom-elements.json file might be added to .gitignore for several reasons:

Automatically Generated: Since custom-elements.json is automatically generated during the build process, it doesn’t need to be stored in version control. It can be regenerated on any machine during the build, so including it in the repository might be considered redundant.

Changes with Each Build: This file can change every time the project is built. Including it in the repository could lead to frequent and unnecessary changes in commit history, cluttering logs and making it harder to track real code changes.

Different Environments: If developers or CI/CD environments use different versions of tools or configurations, the contents of custom-elements.json might differ slightly. This could lead to merge conflicts even if the code changes are minimal.

File Size: In projects with a large number of components, custom-elements.json can become quite large. If the file is not essential for development, it can be excluded from the repository to keep the storage size down.

Documentation in External Systems: If the project is integrated with systems that generate documentation or use component metadata (e.g., Storybook), they might generate or utilize this file themselves, and including it in the repository could lead to data duplication or version mismatches.

In these cases, developers might prefer to generate custom-elements.json locally during each build rather than track it in the repository.

[tshimber]

[tshimber]

If custom-elements.json is in .gitignore and is generated during the build in the CI/CD pipeline but does not make it into the final build of the library, several issues could be causing this:

1. File Not Included in the Publishing Process:
If custom-elements.json is not added to the package published to npm, it might be because it was not copied to the appropriate location before the publish command is run.
Typically, files that are auto-generated in the pipeline should be moved to a folder that is included in the final package (e.g., dist/ or the project root) before the publish command is executed.
2. package.json Not Configured to Include the File:
Make sure custom-elements.json is included in the list of files to be published. In package.json, this can be done using the "files" field. If you use "files", ensure custom-elements.json is listed in that array.
Example in package.json:
json
Copy code
"files": [
"dist/",
"custom-elements.json"
]
3. File Generated After Artifact Copying:
It’s possible that custom-elements.json is generated during the build process, but by the time the artifacts are being packaged for publication, it hasn't been generated yet or wasn't moved to the correct directory. As a result, it isn’t included in the archive sent to npm.
Check the order of steps in your CI/CD pipeline. You might need to adjust the sequence so that the generation and copying of custom-elements.json occur before the packaging and publishing steps.
4. Artifact Excluded by Another Ignoring Mechanism:
If you use .npmignore, it may override .gitignore rules. This means that even if the file was generated and present in the working directory, it could be excluded from publication if listed in .npmignore.
Check .npmignore if it is used and ensure that custom-elements.json is not excluded from publication.

How to Address the Issue:
Check CI/CD Configuration: Ensure that custom-elements.json is generated and moved to the appropriate folder before the publishing stage.
Update package.json: Include custom-elements.json in the list of files to be published.
Review .npmignore: Ensure custom-elements.json is not excluded from publication.

These steps will help ensure that custom-elements.json is included in the final build and available to users of your library.

[amir-ba]

this is closed in favor of 2357