opentwig 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tufan Tunç
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,191 @@
+# OpenTwig 🌿
+
+OpenTwig is an open source personal link page generator that creates beautiful, customizable "link in bio" pages. Instead of relying on third-party services, users can define their configuration and instantly create a fully functional static site they own and control.
+
+## ✨ Features
+
+- 🎨 **Multiple Themes**: Choose from 4 built-in themes (default, dark, minimal, colorful)
+- 📱 **Mobile Responsive**: Optimized for all devices with mobile-first design
+- 🚀 **Fast & Lightweight**: Generates static HTML/CSS with minimal dependencies
+- 🔗 **Easy Link Management**: Simple JSON configuration for all your links
+- 🖼️ **Avatar Support**: Custom profile pictures with automatic processing
+- 📊 **Open Graph Images**: Auto-generated social media preview images
+- 📱 **QR Code Generation**: Built-in QR codes for easy mobile sharing
+- 🎭 **Modal Dialogs**: Support for rich content in footer links
+- 📤 **Share Functionality**: Native Web Share API integration
+- ⚡ **CSS Optimization**: Automatic CSS minification and autoprefixing
+- 🛠️ **CLI Interface**: Simple command-line interface with helpful commands
+
+## 🚀 Quick Start
+
+### Installation & Usage
+
+```bash
+# Create a new project
+npx opentwig --init
+
+# Edit the generated config.json with your information
+# Then generate your page
+npx opentwig
+```
+
+### Prerequisites
+
+- Node.js (v14 or higher)
+- npm or yarn
+
+## 📖 Configuration
+
+OpenTwig uses a simple JSON configuration file (`config.json`) to define your page. Here's the complete configuration structure:
+
+```json
+{
+  "theme": "default",
+  "url": "https://links.yourwebsite.com",
+  "title": "Your Name - opentwig 🌿",
+  "name": "Your Name",
+  "content": "Hello World! Here is my bio.",
+  "minify": true,
+  "avatar": {
+    "path": "./avatar.png"
+  },
+  "links": [
+    {
+      "url": "https://twitter.com",
+      "title": "Twitter"
+    },
+    {
+      "url": "https://instagram.com",
+      "title": "Instagram"
+    }
+  ],
+  "footerLinks": [
+    {
+      "title": "Contact",
+      "url": "mailto:mail@mail.com"
+    },
+    {
+      "title": "Privacy",
+      "content": "Your privacy policy content here..."
+    }
+  ],
+  "share": {
+    "title": "Your Name - opentwig 🌿",
+    "url": "https://links.yourwebsite.com",
+    "text": "Share"
+  }
+}
+```
+
+### Configuration Options
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `theme` | string | Theme name (`default`, `dark`, `minimal`, `colorful`) |
+| `url` | string | Your page URL (for Open Graph and QR codes) |
+| `title` | string | Page title (appears in browser tab) |
+| `name` | string | Your display name |
+| `content` | string | Bio/description text |
+| `minify` | boolean | Enable CSS minification (default: `true`) |
+| `avatar` | object | Avatar image configuration |
+| `avatar.path` | string | Path to your avatar image |
+| `links` | array | Array of link objects with `url` and `title` |
+| `footerLinks` | array | Footer links (can be URLs or modal dialogs) |
+| `share` | object | Web Share API configuration |
+
+## 🎨 Themes
+
+OpenTwig includes 4 beautiful themes:
+
+- **Default**: Clean, modern design with subtle shadows and rounded corners
+- **Dark**: Dark mode variant of the default theme
+- **Minimal**: Simplified, minimalist design
+- **Colorful**: Vibrant color scheme
+
+All themes are mobile-responsive and include:
+- Custom avatar display
+- Link buttons with hover effects
+- Modal dialogs for rich content
+- QR code integration
+- Share button functionality
+
+## 🛠️ CLI Commands
+
+```bash
+# Show help information
+npx opentwig --help
+
+# Create sample config.json
+npx opentwig --init
+
+# Generate page from config.json
+npx opentwig
+```
+
+## 📁 Output Files
+
+OpenTwig generates the following files in the `dist/` directory:
+
+- `index.html` - Main HTML page
+- `style.css` - Processed and optimized CSS
+- `avatar.png` - Processed avatar image
+- `og-image.jpg` - Open Graph image for social sharing
+- `qr.svg` - QR code for mobile sharing
+
+## 🔧 Development
+
+### Project Structure
+
+```
+opentwig/
+├── src/
+│   ├── index.js              # Main entry point
+│   ├── constants.js          # Application constants
+│   └── utils/                # Utility functions
+│       ├── buildPage.js      # Page building logic
+│       ├── generateHTML.js   # HTML generation
+│       ├── generateOGImage.js # Open Graph image creation
+│       ├── generateQR.js     # QR code generation
+│       ├── processCSS.js     # CSS processing and optimization
+│       └── ...
+├── theme/
+│   ├── default/              # Default theme
+│   │   ├── index.js         # Theme template
+│   │   ├── style.css        # Theme styles
+│   │   └── components/      # Reusable components
+│   ├── dark/                # Dark theme
+│   ├── minimal/             # Minimal theme
+│   └── colorful/            # Colorful theme
+└── dist/                    # Generated output
+```
+
+### Key Features Implementation
+
+- **Image Processing**: Uses Sharp for avatar and OG image processing
+- **QR Code Generation**: Uses qrcode library for SVG QR codes
+- **CSS Processing**: PostCSS with autoprefixer and minification
+- **HTML Generation**: Component-based template system
+- **Theme System**: Modular theme architecture with component support
+
+## 🌐 Deployment
+
+Since OpenTwig generates static files, you can deploy to any static hosting service:
+
+- **GitHub Pages**: Push `dist/` folder to a repository
+- **Netlify**: Drag and drop the `dist/` folder
+- **Vercel**: Connect your repository
+- **AWS S3**: Upload files to an S3 bucket
+- **Any web server**: Upload the `dist/` folder to your server
+
+## 📝 License
+
+MIT License - see [LICENSE](LICENSE) file for details
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## 🔗 Links
+
+- [GitHub Repository](https://github.com/tufantunc/opentwig)
+- [NPM Package](https://www.npmjs.com/package/opentwig)

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "opentwig",
+  "version": "1.0.0",
+  "description": "opentwig 🌿 is an open source link in bio page generator.",
+  "main": "src/index.js",
+  "bin": {
+    "opentwig": "./src/index.js"
+  },
+  "scripts": {
+    "start": "node src/index.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tufantunc/opentwig.git"
+  },
+  "keywords": [
+    "link-in-bio",
+    "bio-page",
+    "linktree",
+    "landing-page",
+    "static-site",
+    "generator",
+    "cli",
+    "npx",
+    "open-source"
+  ],
+  "author": "Tufan Tunç",
+  "license": "MIT",
+  "type": "commonjs",
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "preferGlobal": true,
+  "bugs": {
+    "url": "https://github.com/tufantunc/opentwig/issues"
+  },
+  "homepage": "https://github.com/tufantunc/opentwig#readme",
+  "dependencies": {
+    "autoprefixer": "^10.4.21",
+    "html-minifier": "^4.0.0",
+    "postcss": "^8.5.6",
+    "postcss-minify": "^1.2.0",
+    "qrcode": "^1.5.4",
+    "sharp": "^0.34.4"
+  },
+  "browserslist": [
+    "ie 9"
+  ]
+}

package/src/constants.js

@@ -0,0 +1,58 @@
+/**
+ * Constants for OpenTwig
+ * Centralized constants to avoid magic strings and improve maintainability
+ */
+
+const CONSTANTS = {
+    // File paths
+    CONFIG_FILE: 'config.json',
+    OUTPUT_DIR: 'dist',
+    
+    // Output files
+    OUTPUT_FILES: {
+        HTML: 'index.html',
+        CSS: 'style.css',
+        AVATAR: 'avatar.png',
+        OG_IMAGE: 'og-image.jpg',
+        QR_CODE: 'qr.svg'
+    },
+    
+    // Supported themes
+    SUPPORTED_THEMES: ['default', 'dark', 'minimal', 'colorful'],
+    DEFAULT_THEME: 'default',
+    
+    // CLI options
+    CLI_OPTIONS: {
+        HELP: ['--help', '-h'],
+        INIT: ['--init', '-i']
+    },
+    
+    // Messages
+    MESSAGES: {
+        CONFIG_NOT_FOUND: 'Config file not found',
+        CONFIG_EXISTS: 'config.json already exists. Use --force to overwrite.',
+        CONFIG_CREATED: 'Sample config.json created successfully!',
+        CONFIG_EDIT_INSTRUCTIONS: 'Edit config.json with your information and run "npx opentwig" to generate your page.',
+        PAGE_GENERATED: '🎉 Page generated successfully!',
+        UNKNOWN_OPTION: 'Unknown option:',
+        USE_HELP: 'Use --help for usage information.',
+        ERROR_PREFIX: '❌ Error:',
+        SUCCESS_PREFIX: '✅',
+        WARNING_PREFIX: '⚠️',
+        INFO_PREFIX: 'ℹ️'
+    },
+    
+    // URLs
+    GITHUB_URL: 'https://github.com/tufantunc/opentwig',
+    
+    // Default values
+    DEFAULT_TITLE: 'OpenTwig 🌿',
+    DEFAULT_NAME: 'Your Name',
+    DEFAULT_CONTENT: 'Hello World! Here is my bio.',
+    DEFAULT_URL: 'https://links.yourwebsite.com',
+    
+    // Required fields for validation
+    REQUIRED_FIELDS: ['url', 'name']
+};
+
+module.exports = CONSTANTS;

package/src/index.js

@@ -0,0 +1,36 @@
+#! /usr/bin/env node
+'use strict';
+
+const loadConfig = require('./utils/loadConfig');
+const saveFiles = require('./utils/saveFiles');
+const parseArgs = require('./utils/parseArgs');
+const buildPage = require('./utils/buildPage');
+const CONSTANTS = require('./constants');
+
+/**
+ * Main application function with proper error handling
+ */
+const main = async () => {
+    try {
+        // Parse CLI arguments first
+        parseArgs();
+        
+        // Load and validate configuration
+        const config = loadConfig();
+        
+        // Build all page components
+        const { html, css, ogImage, qrImage } = await buildPage(config);
+        
+        // Save all generated files
+        saveFiles(html, css, config.avatar, ogImage, qrImage);
+        
+        // Success message
+        console.log(CONSTANTS.MESSAGES.PAGE_GENERATED);
+        
+    } catch (error) {
+        console.error(`${CONSTANTS.MESSAGES.ERROR_PREFIX} ${error.message}`);
+        process.exit(1);
+    }
+};
+
+main();

package/src/utils/buildPage.js

@@ -0,0 +1,46 @@
+/**
+ * Build page components
+ * Centralizes the page building logic for better organization
+ */
+
+const loadTheme = require('./loadTheme');
+const generateHTML = require('./generateHTML');
+const processCSS = require('./processCSS');
+const generateOGImage = require('./generateOGImage');
+const generateQR = require('./generateQR');
+
+/**
+ * Build all page components from configuration
+ * @param {Object} config - The configuration object
+ * @returns {Promise<Object>} - Object containing all generated components
+ */
+const buildPage = async (config) => {
+    try {
+        // Load theme
+        const theme = loadTheme(config);
+        
+        // Generate HTML
+        const html = generateHTML(config, theme);
+        
+        // Process CSS (async)
+        const css = await processCSS(config);
+        
+        // Generate OG Image (async)
+        const ogImage = await generateOGImage(config);
+        
+        // Generate QR Code (async)
+        const qrImage = await generateQR(config.url);
+        
+        return {
+            html,
+            css,
+            ogImage,
+            qrImage,
+            theme
+        };
+    } catch (error) {
+        throw new Error(`Failed to build page: ${error.message}`);
+    }
+};
+
+module.exports = buildPage;

package/src/utils/configDefaults.js

@@ -0,0 +1,124 @@
+/**
+ * Default configuration values for OpenTwig
+ * This centralizes all default settings to make them easier to maintain
+ */
+
+const DEFAULT_CONFIG = {
+    // Theme settings
+    theme: 'default',
+    
+    // Page settings
+    title: 'OpenTwig 🌿',
+    minify: true,
+    
+    // Content settings
+    name: 'Your Name',
+    content: 'Hello World! Here is my bio.',
+    url: 'https://links.yourwebsite.com',
+    
+    // Avatar settings
+    avatar: {
+        path: './avatar.png'
+    },
+    
+    // Links settings
+    links: [],
+    footerLinks: [],
+    
+    // Share settings
+    share: {
+        title: 'Your Name - opentwig 🌿',
+        url: 'https://links.yourwebsite.com',
+        text: 'Share'
+    }
+};
+
+/**
+ * Sample configuration for --init command
+ * This provides a more complete example with sample data
+ */
+const SAMPLE_CONFIG = {
+    theme: 'default',
+    url: 'https://links.yourwebsite.com',
+    title: 'Your Name - opentwig 🌿',
+    name: 'Your Name',
+    content: 'Hello World! Here is my bio.',
+    minify: true,
+    avatar: {
+        path: 'avatar.png'
+    },
+    links: [
+        {
+            url: 'https://twitter.com',
+            title: 'Twitter'
+        },
+        {
+            url: 'https://instagram.com',
+            title: 'Instagram'
+        },
+        {
+            url: 'https://linkedin.com',
+            title: 'LinkedIn'
+        },
+        {
+            url: 'https://github.com',
+            title: 'GitHub'
+        },
+        {
+            url: 'https://youtube.com',
+            title: 'YouTube'
+        }
+    ],
+    footerLinks: [
+        {
+            title: 'Contact',
+            url: 'mailto:mail@mail.com'
+        },
+        {
+            title: 'Privacy',
+            content: 'When you visit a website, it may store or retrieve information on your browser, mostly in the form of cookies. But its not violating your privacy.'
+        }
+    ],
+    share: {
+        title: 'Your Name - opentwig 🌿',
+        url: 'https://links.yourwebsite.com',
+        text: 'Share'
+    }
+};
+
+/**
+ * Apply default values to a configuration object
+ * @param {Object} config - The configuration object to apply defaults to
+ * @returns {Object} - Configuration with defaults applied
+ */
+const applyDefaults = (config) => {
+    const result = { ...config };
+    
+    // Apply defaults for each key
+    Object.keys(DEFAULT_CONFIG).forEach(key => {
+        if (result[key] === undefined || result[key] === null) {
+            result[key] = DEFAULT_CONFIG[key];
+        }
+    });
+    
+    // Special handling for nested objects
+    if (result.avatar && typeof result.avatar === 'object') {
+        result.avatar = { ...DEFAULT_CONFIG.avatar, ...result.avatar };
+    } else if (!result.avatar) {
+        result.avatar = { ...DEFAULT_CONFIG.avatar };
+    }
+    
+    if (result.share && typeof result.share === 'object') {
+        result.share = { ...DEFAULT_CONFIG.share, ...result.share };
+    } else if (!result.share) {
+        result.share = { ...DEFAULT_CONFIG.share };
+    }
+    
+    return result;
+};
+
+module.exports = {
+    DEFAULT_CONFIG,
+    SAMPLE_CONFIG,
+    applyDefaults
+};

package/src/utils/createSampleConfig.js

@@ -0,0 +1,23 @@
+const fs = require('fs');
+const path = require('path');
+const { SAMPLE_CONFIG } = require('./configDefaults');
+const CONSTANTS = require('../constants');
+
+module.exports = function createSampleConfig() {
+    const sampleConfig = SAMPLE_CONFIG;
+    const configPath = path.join(process.cwd(), CONSTANTS.CONFIG_FILE);
+    
+    if (fs.existsSync(configPath)) {
+        console.log(`${CONSTANTS.MESSAGES.WARNING_PREFIX}  ${CONSTANTS.MESSAGES.CONFIG_EXISTS}`);
+        return;
+    }
+
+    try {
+        fs.writeFileSync(configPath, JSON.stringify(sampleConfig, null, 4));
+        console.log(`${CONSTANTS.MESSAGES.SUCCESS_PREFIX} ${CONSTANTS.MESSAGES.CONFIG_CREATED}`);
+        console.log(`📝 ${CONSTANTS.MESSAGES.CONFIG_EDIT_INSTRUCTIONS}`);
+    } catch (error) {
+        console.error(`${CONSTANTS.MESSAGES.ERROR_PREFIX} creating config.json: ${error.message}`);
+        process.exit(1);
+    }
+};

package/src/utils/generateHTML.js

@@ -0,0 +1,21 @@
+const htmlMinifier = require('html-minifier');
+
+module.exports = function(config, theme) {
+    let html = theme(config);
+    
+    if (config.minify) {
+        const minifiedHtml = htmlMinifier.minify(html, {
+            removeComments: true,
+            collapseWhitespace: true,
+            minifyCSS: true,
+            minifyJS: true
+        });
+        html = minifiedHtml;
+    }
+    
+    // Add created by comment after minification
+    const createdByComment = '<!-- Created by OpenTwig 🌿 - https://github.com/tufantunc/opentwig -->';
+    html = createdByComment + '\n' + html;
+    
+    return html;
+}

package/src/utils/generateOGImage.js

@@ -0,0 +1,45 @@
+const sharp = require('sharp');
+const readImageAsBase64 = require('./readImageAsBase64');
+
+module.exports = async function({name, content, avatar}) {
+    const avatarBase64 = readImageAsBase64(avatar.path);
+    // Create SVG with the same dimensions and styling as the original HTML
+    const svg = `
+        <svg width="1200" height="630" xmlns="http://www.w3.org/2000/svg">
+            <defs>
+                <style>
+                    .name-text { 
+                        font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+                        font-weight: 700; 
+                        font-size: 22px; 
+                        fill: #fdfdfd; 
+                    }
+                    .content-text { 
+                        font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+                        font-size: 14px; 
+                        fill: #fdfdfd; 
+                    }
+                </style>
+            </defs>
+            
+            <!-- Background -->
+            <rect width="1200" height="630" fill="#2d2d2d"/>
+            
+            <!-- Avatar circle background -->
+            <circle cx="552" cy="315" r="48" fill="#dedede"/>
+            
+            <!-- Avatar image (if provided) -->
+            ${avatarBase64 ? `<image href="${avatarBase64}" x="504" y="267" width="96" height="96" clip-path="circle(48px at 48px 48px)"/>` : ''}
+            
+            <!-- Text content -->
+            <text x="660" y="300" class="name-text">${name}</text>
+            <text x="660" y="325" class="content-text">${content}</text>
+        </svg>
+    `;
+    
+    // Convert SVG to JPG
+    const jpgBuffer = await sharp(Buffer.from(svg))
+        .jpeg({ quality: 90 })
+        .toBuffer();
+    return jpgBuffer;
+}

package/src/utils/generateQR.js

@@ -0,0 +1,10 @@
+const QRCode = require('qrcode');
+
+module.exports = async function(url) {
+    const svgString = await QRCode.toString(url, { type: 'svg' });
+    
+    // Remove the white background fill from the SVG
+    const svgWithoutBackground = svgString.replace(/fill="#ffffff"/g, 'fill="transparent"');
+    
+    return svgWithoutBackground;
+}

package/src/utils/loadConfig.js

@@ -0,0 +1,18 @@
+const path = require('path');
+const cwd = process.cwd();
+const fs = require('fs');
+const { applyDefaults } = require('./configDefaults');
+const CONSTANTS = require('../constants');
+
+module.exports = function() {
+    const configPath = path.join(cwd, CONSTANTS.CONFIG_FILE);
+    if (!fs.existsSync(configPath)) {
+        console.error(`${CONSTANTS.MESSAGES.CONFIG_NOT_FOUND}: ${configPath}`);
+        process.exit(1);
+    }
+    
+    const config = require(configPath);
+    
+    // Apply default values to the loaded configuration
+    return applyDefaults(config);
+}

package/src/utils/loadTheme.js

@@ -0,0 +1,23 @@
+const path = require('path');
+const fs = require('fs');
+
+module.exports = function(config) {
+    // Try package directory first (for NPX), then current directory (for local dev)
+    const packageDir = path.dirname(require.main.filename);
+    const currentDir = process.cwd();
+    
+    const themePaths = [
+        path.join(packageDir, '..', 'theme', config.theme, 'index.js'), // NPX package
+        path.join(currentDir, 'theme', config.theme, 'index.js')         // Local development
+    ];
+    
+    const themePath = themePaths.find(p => fs.existsSync(p));
+    
+    if (!themePath) {
+        console.error(`Theme '${config.theme}' not found in any of these locations:`);
+        themePaths.forEach(p => console.error(`  - ${p}`));
+        process.exit(1);
+    }
+
+    return require(themePath);
+}