project-root/ ├── cat/ │ ├── bin/ │ │ └── cat.js │ └── src/ │ └── compiler.js ├──…
- User
project-root/ ├── cat/ │ ├── bin/ │ │ └── cat.js │ └── src/ │ └── compiler.js ├── index.html ├── package.json └── cat.config.json
// cat/src/compiler.js
const fs = require('fs-extra'); const path = require('path'); const glob = require('glob');
/**
- Compiler Function
- @param {string} indexPath - Path to the index.html file.
- @returns {Promise} - Compiled HTML content. */ async function compile(indexPath) { // Read the index.html content let indexContent = await fs.readFile(indexPath, 'utf-8');
// Find all .comp.html files in the project directory const projectRoot = path.dirname(indexPath); const compFiles = glob.sync('/*.comp.html', { cwd: projectRoot, absolute: true, ignore: ['node_modules/', 'cat/**'] // Ignore cat directory to prevent recursion });
// For each component file, inject its content into index.html for (const file of compFiles) { const componentName = path.basename(file, '.comp.html'); const componentContent = await fs.readFile(file, 'utf-8');
// Define a placeholder in index.html where the component should be injected // For example: <!-- inject:componentName --> const placeholder = `<!-- inject:${componentName} -->`; if (indexContent.includes(placeholder)) { // Replace placeholder with component content indexContent = indexContent.replace(placeholder, componentContent); } else { // If no placeholder found, append the component at the end indexContent += `\n<!-- Component: ${componentName} -->\n${componentContent}`; }}
return indexContent; }
module.exports = { compile };
#!/usr/bin/env node
const { program } = require('commander'); const path = require('path'); const fs = require('fs-extra'); const compiler = require('../src/compiler'); const express = require('express');
/**
- Initialize the package.json and cat.config.json */ function initializeProject() { const projectRoot = process.cwd(); const packageJsonPath = path.join(projectRoot, 'package.json'); const configPath = path.join(projectRoot, 'cat.config.json');
// Initialize package.json if it doesn't exist if (!fs.existsSync(packageJsonPath)) { const defaultPackageJson = { name: path.basename(projectRoot), version: "1.0.0", description: "A project using the Cat framework.", main: "index.html", scripts: { cat: "node ./cat/bin/cat.js" }, dependencies: { "commander": "^10.0.0", "express": "^4.18.2", "fs-extra": "^11.1.1", "glob": "^10.3.3" }, author: "Your Name", license: "MIT" }; fs.writeJsonSync(packageJsonPath, defaultPackageJson, { spaces: 2 }); console.log('✅ package.json has been created at the project root.'); console.log('👉 Please run "npm install" to install the dependencies.'); } else { console.log('ℹ️ package.json already exists.'); }
// Initialize cat.config.json if it doesn't exist if (!fs.existsSync(configPath)) { const defaultConfig = { root: 'index.html' }; fs.writeJsonSync(configPath, defaultConfig, { spaces: 2 }); console.log('✅ cat.config.json has been created at the project root.'); } else { console.log('ℹ️ cat.config.json already exists.'); } }
/**
- Start the development server */ async function startServer() { const projectRoot = process.cwd(); const configPath = path.join(projectRoot, 'cat.config.json');
if (!fs.existsSync(configPath)) { console.error('❌ Error: cat.config.json not found. Please run "npm run cat init" first.'); process.exit(1); }
const config = fs.readJsonSync(configPath); const indexPath = path.join(projectRoot, config.root);
if (!fs.existsSync(indexPath)) { console.error(
❌ Error: Root file "${config.root}" not found.); process.exit(1); }const app = express(); const PORT = 3000;
app.get('*', async (req, res) => { try { const compiledHTML = await compiler.compile(indexPath); res.send(compiledHTML); } catch (error) { console.error('❌ Compilation Error:', error); res.status(500).send('Internal Server Error'); } });
app.listen(PORT, () => { console.log(
🚀 Development server is running at http://localhost:${PORT}); }); }// Define the version program.version('1.0.0');
// Define the init command program .command('init') .description('Initialize package.json and cat.config.json at the project root') .action(initializeProject);
// Define the start command program .command('start') .description('Start the development server') .action(startServer);
// Parse the command-line arguments program.parse(process.argv);
Requirements
Our compiler will examine{filename}.comp.htmlto identify the first wrapper that is neither a<script>nor a<style>tag. The name of this tag will be used as the custom element name. If the name lacks a hyphen (-), one will be automatically appended when the custom element is registered, resulting in{name}-cat.Our framework simplifies the use of these components by allowing you to declare them directly where they will be utilized. The compiler identifies which components have been declared and includes them in the JavaScript bundle for registration when the page loads.
Component Syntax
<{comp name}></{comp name}> <script></script> <--- For now, this tag won't be compiled <style></style> <--- For now, this tag won't be compiledSample Usage
<!-- index.html --> <!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8"> <title>Cat Framework App</title> </head> <body> <hello-world></hello-world> </body> </html> <!-- hello.comp.html --> <hello-world> Hi there, everyone </hello-world> - Assistant
Your Cat framework is shaping up nicely! You've established a solid foundation with a clear project structure, a compiler that injects component HTML into the main
index.html, and a CLI tool to initialize and manage the project. Let's review your current implementation in the context of your specified requirements and explore potential enhancements to fully realize the component-based architecture you've envisioned.
Current Implementation Overview
Project Structure
project-root/ ├── cat/ │ ├── bin/ │ │ └── cat.js │ └── src/ │ └── compiler.js ├── index.html ├── package.json └── cat.config.jsonCompiler (
cat/src/compiler.js)- Functionality:
- Reads
index.html. - Scans for all
{filename}.comp.htmlfiles excluding thenode_modulesandcatdirectories. - Injects component content into placeholders within
index.html(e.g.,<!-- inject:componentName -->). - Appends component content at the end of
index.htmlif no placeholder is found.
- Reads
CLI (
cat/bin/cat.js)- Commands:
init: Initializespackage.jsonandcat.config.jsonwith default configurations.start: Starts a development server using Express, compilesindex.htmlwith components, and serves the compiled HTML.
Aligning with Requirements
Component Identification and Custom Element Registration
Your current compiler focuses on injecting component HTML into
index.html. However, based on your requirements, the compiler should also handle:-
Identifying Custom Elements:
- Parse
{filename}.comp.htmlto find the first wrapper tag that's neither<script>nor<style>. - Extract the component name from this tag.
- Parse
-
Ensuring Valid Custom Element Naming:
- If the component name lacks a hyphen (
-), append-catto conform to custom element naming conventions.
- If the component name lacks a hyphen (
-
JavaScript Bundling for Registration:
- Generate JavaScript that registers these custom elements when the page loads.
Sample Usage Alignment
Given your sample usage:
<!-- index.html --> <!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8"> <title>Cat Framework App</title> </head> <body> <hello-world></hello-world> </body> </html> <!-- hello.comp.html --> <hello-world> Hi there, everyone </hello-world>The compiler should:
- Identify
<hello-world>as a custom element. - Ensure it follows naming conventions (it already includes a hyphen).
- Register
<hello-world>as a custom element, potentially enhancing it with JavaScript if needed.
Proposed Enhancements
To fully meet your framework's requirements, consider the following enhancements to your compiler and overall setup:
1. Enhancing the Compiler to Register Custom Elements
a. Extracting Component Names and Ensuring Naming Conventions
Modify the compiler to parse each
.comp.htmlfile, extract the component name, and ensure it follows the hyphenated naming convention.Sample Implementation:
// cat/src/compiler.js const fs = require('fs-extra'); const path = require('path'); const glob = require('glob'); /** * Compiler Function * @param {string} indexPath - Path to the index.html file. * @returns {Promise<string>} - Compiled HTML content. */ async function compile(indexPath) { // Read the index.html content let indexContent = await fs.readFile(indexPath, 'utf-8'); // Find all .comp.html files in the project directory const projectRoot = path.dirname(indexPath); const compFiles = glob.sync('**/*.comp.html', { cwd: projectRoot, absolute: true, ignore: ['node_modules/**', 'cat/**'] }); const components = []; // For each component file, process its content for (const file of compFiles) { const componentNameRaw = path.basename(file, '.comp.html'); const componentContent = await fs.readFile(file, 'utf-8'); // Extract the first tag that's not <script> or <style> const tagMatch = componentContent.match(/<(\w[-\w]*)[^>]*>/); if (!tagMatch) { console.warn(`⚠️ No valid wrapper tag found in ${file}. Skipping.`); continue; } let componentName = tagMatch[1]; // Ensure the component name has a hyphen if (!componentName.includes('-')) { componentName = `${componentName}-cat`; } // Store component details for registration components.push({ name: componentName, content: componentContent }); // Define a placeholder in index.html where the component should be injected const placeholder = `<!-- inject:${componentName} -->`; if (indexContent.includes(placeholder)) { // Replace placeholder with component content indexContent = indexContent.replace(placeholder, componentContent); } else { // If no placeholder found, append the component at the end indexContent += `\n<!-- Component: ${componentName} -->\n${componentContent}`; } } // Generate the JavaScript for registering custom elements const registrationScript = generateRegistrationScript(components); // Inject the registration script before closing </body> tag indexContent = indexContent.replace('</body>', `<script>\n${registrationScript}\n</script>\n</body>`); return indexContent; } /** * Generates JavaScript code to register custom elements * @param {Array} components - List of components with name and content * @returns {string} - JavaScript code as string */ function generateRegistrationScript(components) { let script = ''; components.forEach(({ name, content }) => { script += ` class ${toPascalCase(name)} extends HTMLElement { constructor() { super(); this.attachShadow({ mode: 'open' }); this.shadowRoot.innerHTML = \`${content}\`; } } customElements.define('${name}', ${toPascalCase(name)}); `; }); return script; } /** * Converts a kebab-case string to PascalCase * @param {string} str - Kebab-case string * @returns {string} - PascalCase string */ function toPascalCase(str) { return str .split('-') .map(word => word.charAt(0).toUpperCase() + word.slice(1)) .join(''); } module.exports = { compile };Explanation:
-
Component Parsing:
- Uses a regular expression to find the first tag that's not
<script>or<style>. - Ensures the component name contains a hyphen; appends
-catif it doesn't.
- Uses a regular expression to find the first tag that's not
-
Registration Script Generation:
- For each component, it generates a JavaScript class extending
HTMLElement. - Attaches a shadow DOM and injects the component's HTML content.
- Registers the custom element with
customElements.define.
- For each component, it generates a JavaScript class extending
-
Injecting the Registration Script:
- Appends the generated script before the closing
</body>tag inindex.html.
- Appends the generated script before the closing
Benefits:
- Automates custom element registration.
- Ensures naming conventions are enforced.
- Encapsulates component styles and markup using Shadow DOM.
2. Handling
<script>and<style>Tags Within ComponentsCurrently, your compiler ignores
<script>and<style>tags within component files. If you plan to support scripting and styling within components, consider the following enhancements:a. Extract and Process
<style>Tags-
Purpose: Allow components to encapsulate their styles.
-
Implementation:
- Extract
<style>content from the component HTML. - Inject it into the component's shadow DOM.
- Extract
b. Extract and Process
<script>Tags-
Purpose: Enable components to have their own behavior.
-
Implementation:
- Extract
<script>content. - Ensure that scripts are executed within the component's context.
- Extract
Enhanced
generateRegistrationScriptFunction:function generateRegistrationScript(components) { let script = ''; components.forEach(({ name, content }) => { // Extract <style> content const styleMatch = content.match(/<style[^>]*>([\s\S]*?)<\/style>/); const styles = styleMatch ? styleMatch[1] : ''; // Extract <script> content const scriptMatch = content.match(/<script[^>]*>([\s\S]*?)<\/script>/); const componentScript = scriptMatch ? scriptMatch[1] : ''; // Extract the template (excluding <style> and <script>) const template = content .replace(/<script[^>]*>[\s\S]*?<\/script>/, '') .replace(/<style[^>]*>[\s\S]*?<\/style>/, ''); script += ` class ${toPascalCase(name)} extends HTMLElement { constructor() { super(); this.attachShadow({ mode: 'open' }); this.shadowRoot.innerHTML = \` ${styles ? `<style>${styles}</style>` : ''} ${template} \`; ${componentScript} } } customElements.define('${name}', ${toPascalCase(name)}); `; }); return script; }Explanation:
-
Style Handling:
- Extracts
<style>content and injects it within a<style>tag inside the shadow DOM, ensuring styles are scoped to the component.
- Extracts
-
Script Handling:
- Extracts
<script>content and includes it in the component's constructor, allowing behavior to be defined per component.
- Extracts
Caution:
- Security: Embedding scripts directly can lead to security vulnerabilities. Consider sanitizing or restricting script content.
- Performance: Excessive inline scripts can impact performance. For larger projects, think about bundling scripts separately.
3. Optimizing Component Discovery
To make component discovery more efficient and avoid potential conflicts:
-
Use Namespaces or Prefixes: Consider organizing components within specific directories or using naming conventions that reduce the risk of duplicate component names.
-
Dynamic Imports: Instead of injecting all component scripts into
index.html, explore dynamic imports to load components as needed. This can improve initial load times.
4. Enhancing the CLI with Additional Commands
Expand your CLI to offer more flexibility and control:
-
Build Command: For production builds that minify and optimize assets.
program .command('build') .description('Build the project for production') .action(buildProject); -
Add Component Command: To scaffold new components easily.
program .command('add <componentName>') .description('Add a new component') .action(addComponent);
Sample
addComponentImplementation:async function addComponent(componentName) { const projectRoot = process.cwd(); const compDir = path.join(projectRoot, 'components'); await fs.ensureDir(compDir); let actualName = componentName; if (!componentName.includes('-')) { actualName = `${componentName}-cat`; } const compPath = path.join(compDir, `${actualName}.comp.html`); if (await fs.pathExists(compPath)) { console.error(`❌ Component "${actualName}" already exists.`); process.exit(1); } const template = ` <${actualName}> <!-- Your component HTML here --> </${actualName}> <script> // Your component JavaScript here </script> <style> /* Your component CSS here */ </style> `.trim(); await fs.writeFile(compPath, template, 'utf-8'); console.log(`✅ Component "${actualName}" has been created at ${compPath}.`); }5. Improving the Development Server
Enhance the development experience by adding features such as:
-
Live Reloading: Automatically reload the browser when files change.
Implementation Suggestion:
- Use libraries like
chokidarto watch for file changes. - Integrate WebSocket communication to notify the browser to reload.
- Use libraries like
-
Error Handling: Provide more descriptive error messages and possibly a debug mode.
6. Documentation and Usage Examples
Provide comprehensive documentation and usage examples to help developers understand and utilize the Cat framework effectively.
Documentation Topics:
- Getting Started: Installation, initialization, and running the development server.
- Component Creation: Guidelines on creating and organizing components.
- Styling and Scripting: Best practices for encapsulating styles and behaviors.
- Advanced Features: Extending the framework, customizing the build process, etc.
- Troubleshooting: Common issues and solutions.
Final Thoughts
Your Cat framework demonstrates a thoughtful approach to building a component-based architecture with custom elements. By enhancing the compiler to handle component registration more comprehensively, ensuring proper naming conventions, and expanding CLI capabilities, you can create a robust and developer-friendly tool.
Consider implementing the proposed enhancements incrementally, testing each feature thoroughly to maintain stability. Additionally, gathering feedback from potential users can provide valuable insights into further improvements and use cases.
Feel free to reach out if you need assistance with specific implementations or encounter challenges along the way. Happy coding!
- Functionality: