create-cloudinary-react 1.0.0-beta.1

package/.github/CODEOWNERS

@@ -0,0 +1,4 @@
+# Code Owners - Only these people can approve pull requests
+# All files in the repository require Code Owner approval
+
+* @strausr

package/.github/workflows/release.yml

@@ -0,0 +1,45 @@
+name: Release
+
+on:
+  workflow_dispatch:
+
+permissions:
+  contents: write
+  id-token: write
+  issues: write
+  pull-requests: write
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Verify admin permissions
+        run: |
+          PERMISSION=$(curl -s -H "Authorization: token ${{ secrets.GITHUB_TOKEN }}" \
+            "https://api.github.com/repos/${{ github.repository }}/collaborators/${{ github.actor }}/permission" \
+            | grep -o '"permission":"[^"]*"' | cut -d'"' -f4)
+          
+          if [ "$PERMISSION" != "admin" ]; then
+            echo "Error: Only repository admins can trigger releases. Current permission: $PERMISSION"
+            exit 1
+          fi
+          
+          echo "✓ Verified admin permission for ${{ github.actor }}"
+
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+          registry-url: 'https://registry.npmjs.org'
+
+      - run: npm ci
+
+      - run: npm test --if-present
+
+      - name: Release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: npx semantic-release

package/.husky/commit-msg

@@ -0,0 +1 @@
+npx --no -- commitlint --edit ${1}

package/.releaserc.json

@@ -0,0 +1,23 @@
+{
+  "branches": [
+    "main",
+    {
+      "name": "beta",
+      "prerelease": true
+    }
+  ],
+  "plugins": [
+    "@semantic-release/commit-analyzer",
+    "@semantic-release/release-notes-generator",
+    "@semantic-release/changelog",
+    "@semantic-release/npm",
+    [
+      "@semantic-release/git",
+      {
+        "assets": ["package.json", "CHANGELOG.md"],
+        "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
+      }
+    ],
+    "@semantic-release/github"
+  ]
+}

package/CHANGELOG.md

@@ -0,0 +1,6 @@
+# Changelog
+
+## [1.0.0] - TBD
+
+### Added
+- Initial release

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Cloudinary
+
+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,75 @@
+# create-cloudinary-react
+
+> **Beta Release** - This is a beta version. We welcome feedback and bug reports!
+
+Part of the [Cloudinary Developers](https://github.com/cloudinary-devs) organization.
+
+Scaffold a Cloudinary React + Vite + TypeScript project with interactive setup.
+
+## Prerequisites
+
+- Node.js 18+ installed
+- A Cloudinary account (free tier available)
+  - [Sign up for free](https://cloudinary.com/users/register/free)
+  - Your cloud name is in your [dashboard](https://console.cloudinary.com/app/home/dashboard)
+
+## Usage
+
+```bash
+npx create-cloudinary-react
+```
+
+The CLI will prompt you for:
+- Project name
+- **Cloudinary cloud name** (found in your [dashboard](https://console.cloudinary.com/app/home/dashboard))
+- Upload preset (optional - required for uploads, but transformations work without it)
+- AI coding assistant(s) you're using (Cursor, GitHub Copilot, Claude, etc.)
+- Whether to install dependencies
+- Whether to start dev server
+
+## Features
+
+- ✅ Interactive setup with validation
+- ✅ Pre-configured Cloudinary React SDK
+- ✅ TypeScript + Vite + React 19
+- ✅ Typed Upload Widget component
+- ✅ Environment variables with VITE_ prefix
+- ✅ Multi-tool AI assistant support (Cursor, GitHub Copilot, Claude, and more)
+- ✅ MCP configuration for Cloudinary integration
+- ✅ ESLint + TypeScript configured
+
+## AI Assistant Support
+
+During setup, you'll be asked which AI coding assistant(s) you're using. The CLI will generate the appropriate configuration files:
+
+- ✅ **Cursor** → `.cursorrules` + `.cursor/mcp.json` (if selected)
+- ✅ **GitHub Copilot** → `.github/copilot-instructions.md`
+- ✅ **Claude Code / Claude Desktop** → `.claude`, `claude.md` + `.cursor/mcp.json` (if selected)
+- ✅ **Generic AI tools** → `AI_INSTRUCTIONS.md`, `PROMPT.md`
+
+**MCP Configuration**: The `.cursor/mcp.json` file is automatically generated if you select Cursor or Claude, as it works with both tools.
+
+These rules help AI assistants understand Cloudinary React SDK patterns, common errors, and best practices. The generated app also includes an "AI Prompts" section with ready-to-use suggestions for your AI assistant.
+
+## Development
+
+This project uses [Conventional Commits](https://www.conventionalcommits.org/) for version management.
+
+### Commit Format
+
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+**Types:**
+- `feat`: New feature
+- `fix`: Bug fix
+- `docs`: Documentation changes
+- `refactor`: Code refactoring
+- `perf`: Performance improvements
+- `chore`: Other changes
+

package/cli.js

@@ -0,0 +1,283 @@
+#!/usr/bin/env node
+
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'fs';
+import { execSync } from 'child_process';
+import inquirer from 'inquirer';
+import chalk from 'chalk';
+import fs from 'fs-extra';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const TEMPLATES_DIR = join(__dirname, 'templates');
+
+// Validate cloud name format
+function isValidCloudName(name) {
+  return /^[a-z0-9_-]+$/.test(name) && name.length > 0;
+}
+
+// Validate project name
+function isValidProjectName(name) {
+  return /^[a-z0-9_-]+$/i.test(name) && name.length > 0;
+}
+
+async function main() {
+  console.log(chalk.cyan.bold('\n🚀 Cloudinary React + Vite Boilerplate\n'));
+  console.log(chalk.gray('💡 Need a Cloudinary account? Sign up for free: https://cloudinary.com/users/register/free\n'));
+
+  const answers = await inquirer.prompt([
+    {
+      type: 'input',
+      name: 'projectName',
+      message: 'Project name:',
+      default: 'my-cloudinary-app',
+      validate: (input) => {
+        if (!input.trim()) {
+          return 'Project name cannot be empty';
+        }
+        if (!isValidProjectName(input)) {
+          return 'Project name can only contain letters, numbers, hyphens, and underscores';
+        }
+        if (existsSync(input)) {
+          return `Directory "${input}" already exists. Please choose a different name.`;
+        }
+        return true;
+      },
+    },
+    {
+      type: 'input',
+      name: 'cloudName',
+      message: 'Cloudinary Cloud Name:',
+      description: chalk.gray(
+        'Your cloud name is shown in your dashboard: https://console.cloudinary.com/app/home/dashboard'
+      ),
+      validate: (input) => {
+        if (!input.trim()) {
+          return chalk.yellow(
+            'Cloud name is required.\n' +
+            '  → Sign up: https://cloudinary.com/users/register/free\n' +
+            '  → Find your cloud name: https://console.cloudinary.com/app/home/dashboard'
+          );
+        }
+        if (!isValidCloudName(input)) {
+          return 'Cloud name can only contain lowercase letters, numbers, hyphens, and underscores';
+        }
+        return true;
+      },
+    },
+    {
+      type: 'confirm',
+      name: 'hasUploadPreset',
+      message: 'Do you have an unsigned upload preset? (Required for uploads, optional for transformations)',
+      default: false,
+      description: chalk.gray(
+        'Upload presets enable client-side uploads. You can set one up later at:\n' +
+        'https://console.cloudinary.com/app/settings/upload/presets'
+      ),
+    },
+    {
+      type: 'input',
+      name: 'uploadPreset',
+      message: 'Upload Preset Name:',
+      when: (answers) => answers.hasUploadPreset,
+      validate: (input) => {
+        if (!input.trim()) {
+          return 'Upload preset name cannot be empty';
+        }
+        return true;
+      },
+    },
+    {
+      type: 'checkbox',
+      name: 'aiTools',
+      message: 'Which AI coding assistant(s) are you using? (Select all that apply)',
+      choices: [
+        { name: 'Cursor', value: 'cursor' },
+        { name: 'GitHub Copilot', value: 'copilot' },
+        { name: 'Claude Code / Claude Desktop', value: 'claude' },
+        { name: 'Other / Generic AI tools', value: 'generic' },
+      ],
+      default: ['cursor'],
+    },
+    {
+      type: 'confirm',
+      name: 'installDeps',
+      message: 'Install dependencies now?',
+      default: true,
+    },
+    {
+      type: 'confirm',
+      name: 'startDev',
+      message: 'Start development server?',
+      default: false,
+      when: (answers) => answers.installDeps,
+    },
+  ]);
+
+  const { projectName, cloudName, uploadPreset, aiTools, installDeps, startDev } = answers;
+
+  console.log(chalk.blue('\n📦 Creating project...\n'));
+
+  // Create project directory
+  const projectPath = join(process.cwd(), projectName);
+  mkdirSync(projectPath, { recursive: true });
+
+  // Template replacement function
+  function replaceTemplate(content, vars) {
+    let result = content;
+    Object.keys(vars).forEach((key) => {
+      const regex = new RegExp(`\\{\\{${key}\\}\\}`, 'g');
+      result = result.replace(regex, vars[key]);
+    });
+    return result;
+  }
+
+  // Template variables
+  const templateVars = {
+    PROJECT_NAME: projectName,
+    CLOUD_NAME: cloudName,
+    UPLOAD_PRESET: uploadPreset || '',
+  };
+
+  // Function to copy template file
+  function copyTemplate(relativePath, outputPath = null) {
+    const templatePath = join(TEMPLATES_DIR, relativePath);
+    const finalPath = outputPath || join(projectPath, relativePath.replace('.template', ''));
+    
+    // Create directory if needed
+    const finalDir = dirname(finalPath);
+    if (!existsSync(finalDir)) {
+      mkdirSync(finalDir, { recursive: true });
+    }
+
+    if (existsSync(templatePath)) {
+      const content = readFileSync(templatePath, 'utf-8');
+      const processed = replaceTemplate(content, templateVars);
+      writeFileSync(finalPath, processed);
+    }
+  }
+
+  // Copy all template files
+  const filesToCopy = [
+    'package.json.template',
+    'vite.config.ts.template',
+    'tsconfig.json.template',
+    'tsconfig.app.json.template',
+    'tsconfig.node.json.template',
+    'eslint.config.js.template',
+    '.gitignore.template',
+    '.env.template',
+    'index.html.template',
+    'README.md.template',
+    'src/cloudinary/config.ts.template',
+    'src/cloudinary/UploadWidget.tsx.template',
+    'src/App.tsx.template',
+    'src/main.tsx.template',
+    'src/index.css.template',
+    'src/App.css.template',
+  ];
+
+  filesToCopy.forEach((file) => {
+    copyTemplate(file);
+  });
+
+  // Create AI rules based on user's tool selection
+  const aiRulesTemplatePath = join(TEMPLATES_DIR, '.cursorrules.template');
+  if (existsSync(aiRulesTemplatePath) && aiTools && aiTools.length > 0) {
+    const aiRulesContent = replaceTemplate(
+      readFileSync(aiRulesTemplatePath, 'utf-8'),
+      templateVars
+    );
+
+    // Generate files based on selected tools
+    if (aiTools.includes('cursor')) {
+      writeFileSync(join(projectPath, '.cursorrules'), aiRulesContent);
+    }
+
+    if (aiTools.includes('copilot')) {
+      const githubDir = join(projectPath, '.github');
+      mkdirSync(githubDir, { recursive: true });
+      writeFileSync(join(githubDir, 'copilot-instructions.md'), aiRulesContent);
+    }
+
+    if (aiTools.includes('claude')) {
+      writeFileSync(join(projectPath, '.claude'), aiRulesContent);
+      writeFileSync(join(projectPath, 'claude.md'), aiRulesContent);
+    }
+
+    if (aiTools.includes('generic')) {
+      writeFileSync(join(projectPath, 'AI_INSTRUCTIONS.md'), aiRulesContent);
+      writeFileSync(join(projectPath, 'PROMPT.md'), aiRulesContent);
+    }
+
+    // Generate MCP configuration if using Cursor or Claude (MCP works with both)
+    if (aiTools.includes('cursor') || aiTools.includes('claude')) {
+      const mcpTemplatePath = join(TEMPLATES_DIR, '.cursor/mcp.json.template');
+      if (existsSync(mcpTemplatePath)) {
+        const cursorDir = join(projectPath, '.cursor');
+        mkdirSync(cursorDir, { recursive: true });
+        const mcpContent = replaceTemplate(
+          readFileSync(mcpTemplatePath, 'utf-8'),
+          templateVars
+        );
+        writeFileSync(join(cursorDir, 'mcp.json'), mcpContent);
+      }
+    }
+  }
+
+  // Copy vite.svg to public directory
+  const viteSvgPath = join(projectPath, 'public', 'vite.svg');
+  mkdirSync(join(projectPath, 'public'), { recursive: true });
+  const viteSvg = '<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" aria-hidden="true" role="img" class="iconify iconify--logos" width="31.88" height="32" preserveAspectRatio="xMidYMid meet" viewBox="0 0 256 257"><defs><linearGradient id="IconifyId1813088fe1fbc01fb466" x1="-.828%" x2="57.636%" y1="7.652%" y2="78.411%"><stop offset="0%" stop-color="#41D1FF"></stop><stop offset="100%" stop-color="#BD34FE"></stop></linearGradient><linearGradient id="IconifyId1813088fe1fbc01fb467" x1="43.376%" x2="50.316%" y1="2.242%" y2="89.03%"><stop offset="0%" stop-color="#FFEA83"></stop><stop offset="8.333%" stop-color="#FFDD35"></stop><stop offset="100%" stop-color="#FFA800"></stop></linearGradient></defs><path fill="url(#IconifyId1813088fe1fbc01fb466)" d="M255.153 37.938L134.897 252.976c-2.483 4.44-8.862 4.466-11.382.048L.875 37.958c-2.746-4.814 1.371-10.646 6.827-9.67l120.385 21.517a6.537 6.537 0 0 0 2.322-.004l117.867-21.483c5.438-.991 9.574 4.796 6.877 9.62Z"></path><path fill="url(#IconifyId1813088fe1fbc01fb467)" d="M185.432.063L96.44 17.501a3.268 3.268 0 0 0-2.634 3.014l-5.474 92.456a3.268 3.268 0 0 0 3.997 3.378l24.777-5.718c2.318-.535 4.413 1.507 3.936 3.838l-7.361 36.047c-.495 2.426 1.782 4.5 4.151 3.78l15.304-4.649c2.372-.72 4.652 1.36 4.15 3.788l-11.698 56.621c-.732 3.542 3.979 5.473 5.943 2.437l1.313-2.028l72.516-144.72c1.215-2.423-.88-5.186-3.54-4.672l-25.505 4.922c-2.396.462-4.435-1.77-3.759-4.114l16.646-57.705c.677-2.35-1.37-4.583-3.769-4.113Z"></path></svg>';
+  writeFileSync(viteSvgPath, viteSvg);
+
+  console.log(chalk.green('✅ Project created successfully!\n'));
+
+  if (!answers.hasUploadPreset) {
+    console.log(chalk.yellow('\n📝 Note: Upload preset not configured'));
+    console.log(chalk.gray('   • Transformations will work with sample images'));
+    console.log(chalk.gray('   • Uploads require an unsigned upload preset'));
+    console.log(chalk.cyan('\n   To enable uploads:'));
+    console.log(chalk.cyan('   1. Go to https://console.cloudinary.com/app/settings/upload/presets'));
+    console.log(chalk.cyan('   2. Click "Add upload preset"'));
+    console.log(chalk.cyan('   3. Set it to "Unsigned" mode'));
+    console.log(chalk.cyan('   4. Add the preset name to your .env file\n'));
+  }
+
+  if (installDeps) {
+    console.log(chalk.blue('📦 Installing dependencies...\n'));
+    try {
+      process.chdir(projectPath);
+      execSync('npm install', { stdio: 'inherit' });
+      console.log(chalk.green('\n✅ Dependencies installed!\n'));
+
+      if (startDev) {
+        console.log(chalk.blue('🚀 Starting development server...\n'));
+        execSync('npm run dev', { stdio: 'inherit' });
+      } else {
+        console.log(chalk.cyan(`\n📁 Project created at: ${projectPath}`));
+        console.log(chalk.cyan(`\nNext steps:`));
+        console.log(chalk.cyan(`  cd ${projectName}`));
+        console.log(chalk.cyan(`  npm run dev\n`));
+      }
+    } catch (error) {
+      console.error(chalk.red('\n❌ Error installing dependencies:'), error.message);
+      console.log(chalk.cyan(`\nYou can install manually:`));
+      console.log(chalk.cyan(`  cd ${projectName}`));
+      console.log(chalk.cyan(`  npm install\n`));
+    }
+  } else {
+    console.log(chalk.cyan(`\n📁 Project created at: ${projectPath}`));
+    console.log(chalk.cyan(`\nNext steps:`));
+    console.log(chalk.cyan(`  cd ${projectName}`));
+    console.log(chalk.cyan(`  npm install`));
+    console.log(chalk.cyan(`  npm run dev\n`));
+  }
+}
+
+main().catch((error) => {
+  console.error(chalk.red('❌ Error:'), error.message);
+  process.exit(1);
+});

package/commitlint.config.js

@@ -0,0 +1,23 @@
+export default {
+  extends: ['@commitlint/config-conventional'],
+  rules: {
+    'type-enum': [
+      2,
+      'always',
+      [
+        'feat',     // New feature
+        'fix',      // Bug fix
+        'docs',     // Documentation changes
+        'style',    // Code style changes (formatting, etc.)
+        'refactor', // Code refactoring
+        'perf',     // Performance improvements
+        'test',     // Adding or updating tests
+        'build',    // Build system changes
+        'ci',       // CI configuration changes
+        'chore',    // Other changes that don't modify src or test files
+        'revert',   // Revert a previous commit
+      ],
+    ],
+    'subject-case': [2, 'never', ['start-case', 'pascal-case', 'upper-case']],
+  },
+};

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "create-cloudinary-react",
+  "version": "1.0.0-beta.1",
+  "description": "Scaffold a Cloudinary React + Vite + TypeScript project with interactive setup",
+  "type": "module",
+  "bin": {
+    "create-cloudinary-react": "./cli.js"
+  },
+  "keywords": [
+    "cloudinary",
+    "react",
+    "vite",
+    "typescript",
+    "boilerplate",
+    "scaffold"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cloudinary-devs/create-cloudinary-react.git"
+  },
+  "homepage": "https://github.com/cloudinary-devs/create-cloudinary-react#readme",
+  "bugs": {
+    "url": "https://github.com/cloudinary-devs/create-cloudinary-react/issues"
+  },
+  "dependencies": {
+    "inquirer": "^9.2.15",
+    "chalk": "^5.3.0",
+    "fs-extra": "^11.2.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "semantic-release": "semantic-release"
+  },
+  "devDependencies": {
+    "@commitlint/cli": "^19.6.0",
+    "@commitlint/config-conventional": "^19.6.0",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "husky": "^9.1.7",
+    "semantic-release": "^23.0.0"
+  }
+}

package/templates/.cursor/mcp.json.template

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "cloudinary-asset-mgmt": {
+      "url": "https://asset-management.mcp.cloudinary.com/sse"
+    },
+    "cloudinary-env-config": {
+      "url": "https://environment-config.mcp.cloudinary.com/sse"
+    }
+  }
+}