Our Recommendations

• Folder Structure
  1. CSS: Generally kept in the styles directory at root (if any). Preprocessors like Sass or Less act in the same directory.
  2. JS: Generally kept in the scripts directory at root (if any).
  3. Usable HTML: Generally stored in the base directory (for the most part, historically). Routes are allotted their own directories.
  4. Child Chasse Files: Should be stored in a src directory at root (if any). Routes can be allotted their own directories (within src).
  5. Parent Chasse Files: May be stored in src along the child files. However, as project grows larger with different sections to it, parent Chasse files should go in src/parents (this is the recommended convention). Use the option -p to specify the parent path during the conversions into resultant files.
• File Names
  1. Usable HTML: Generally named in kebab-case according to the URL route.
  2. Chasse Files: Must be named with the extension .chasse.html. It is a requirement, not a convention (made to separate resultant files from these files).
  3. Child Chasse Files: Should be named exactly similar to the usable HTML files (because after direct conversion, the names remain the same).
  4. Parent Chasse Files: Should not be loosely named as parent.chasse.html. It should clearly describe the purpose it addresses. In case of multiple reusable components, do not club them up into a single file. Make different parent Chasse files and separate them (inheriting from multiple parent files are supported). You cannot have same component names across the entire application (even if it is in different files).
• Defining Components
  1. General: In general, we use components for reusability. So items like footers, navbars, menus, meta tags are fair game.
  2. Lean Development: This means that the developer wants to work with less verbose and clean code (which also means shipping of bulk HTML code as components in parent Chasse files). Define multiple parent Chasse files in this case, each corresponding to a child file.
  3. Bulky Text: In case we have too much of text in an HTML element that makes the file look clumsy or bulky, ship 'em as components!!
  4. Extreme Customizations: Have a highly customized element? It might be simple in general, but has many CSS framework (like Tailwind...?) classes attached to it. Ship 'em as components!!
• Example Filesystem
  1. This seeks to illustrate how to establish a filesystem corresponding to all conventions. There is no hard and fast rule to follow it to the teeth, of course.
  2. General: We move general components like footers, navbars and meta tags any other component that can be common across the entire app into src/parents/root.chasse.html.
  3. Lean Components: These components are specific to every child Chasse file and will contain the bulk of HTML of its corresponding child. So if a child is named as src/index.chasse.html, the lean components would go in src/parents/index.chasse.html.
  4. Bulky Text: We may choose to store these components in src/parents/text.chasse.html.
  5. Extreme Customizations: This is a rather general point that cannot have a specific convention to along with all cases. There may be many different custom elements, many similar custom elements, few heavily custom elements that are all different. So there is quite a bit of leeway here as to the standards.
• Version Control
  1. Solo: You can choose to commit or not commit the Chasse files into version control, since you are the only developer here.
  2. Teams: It is strongly recommended to check in your Chasse files into version control, for collaboration between all developers.
  3. Branches: It is good to have separate development (this contains the Chasse files) and production (this does not, because the less the clutter - the better) branches. If there is a testing or a staging branch, the Chasse files should be kept out of it.
• Practices
  1. JS Frameworks: All JS frameworks already have utilities to deal with components. Hence, use of Chasse with any framework is highly discouraged.
  2. Development: Chasse encourages lean development (shipping off HTML as components parent files) so that the child files look clean and tidy. That said, it can also be used for just the generally reusable elements.
  3. npm: If you project has to use package managers like npm, it is not worth using Chasse (since that tool always has a library up its sleeve for component management). One of the reasons behind the creation of this utility was to do away with package managers, libraries, dependency hell and configuration-less deployment. Simultaneous use of the two is highly discouraged.
  4. Leave the Resultant Files Alone: It is encouraged to always develop and code on the Chasse files. Leave the generated HTML files alone for the browser to interpret. Touching it would also mean corrections in the Chasse files. Remember to use relative paths for scripts, assets and stylesheets with respect to the directory where resultant files would live.
  5. Overusing Components: Unnecessary use of components is highly discouraged. In fact, it undoes the entire solution. Examples include script and style components (just use JS or CSS files in script and styles), micro-components (just use regular HTML), multiple similar components for different situations or child files (break up the large ones into smaller reusable components), etc.
  6. Using the Command: It is recommended to write all optional arguments towards the end of the command after both the positional arguments.