feat: add cloneProject + stackblitz-clone

Author: danielroe

README.md

@@ -36,11 +36,17 @@ Download:  https://stackblitz.zip/edit/nuxt-starter-k7spa3r4
 ## CLI
 
 ```bash
-# download a project
+# download a project as a zip file
 npx stackblitz-zip https://stackblitz.com/edit/nuxt-starter-k7spa3r4
 
-# specify output path
+# specify output path for zip
 npx stackblitz-zip https://stackblitz.com/edit/nuxt-starter-k7spa3r4 my-project.zip
+
+# clone project to a directory
+npx stackblitz-clone https://stackblitz.com/edit/nuxt-starter-k7spa3r4
+
+# clone to a specific directory
+npx stackblitz-clone https://stackblitz.com/edit/nuxt-starter-k7spa3r4 ./my-project
 ```
 
 ## Programmatic Usage
@@ -54,9 +60,9 @@ npm install stackblitz-zip
 ### Node.js
 
 ```typescript
-import { downloadToFile, parseUrl } from 'stackblitz-zip'
+import { cloneProject, downloadToFile, parseUrl } from 'stackblitz-zip'
 
-// download from a URL
+// download from a URL as a zip file
 const projectId = parseUrl('https://stackblitz.com/edit/nuxt-starter-k7spa3r4')
 await downloadToFile({ projectId, outputPath: './output.zip' })
 
@@ -65,6 +71,12 @@ await downloadToFile({
   projectId: 'nuxt-starter-k7spa3r4',
   outputPath: './my-project.zip',
 })
+
+// clone project to a directory
+await cloneProject({
+  projectId: 'nuxt-starter-k7spa3r4',
+  outputPath: './my-project',
+})
 ```
 
 ### Web APIs
@@ -140,6 +152,20 @@ Downloads a StackBlitz project and returns the path to the created zip file.
 - `maxTotalSize` (number, optional): Maximum total project size in bytes. Defaults to `104857600` (100MB)
 - `verbose` (boolean, optional): Enable console logging. Defaults to `false`
 
+### `cloneProject(options: CloneOptions): Promise<string>`
+
+Clones a StackBlitz project by creating all files in a target directory.
+
+**Options:**
+- `projectId` (string, required): The StackBlitz project ID
+- `outputPath` (string, optional): Path where the project directory should be created. Defaults to `<project-id>/`
+- `timeout` (number, optional): Timeout in milliseconds for loading the project. Defaults to `30000` (30 seconds)
+- `maxFileSize` (number, optional): Maximum size per file in bytes. Defaults to `10485760` (10MB)
+- `maxTotalSize` (number, optional): Maximum total project size in bytes. Defaults to `104857600` (100MB)
+- `verbose` (boolean, optional): Enable console logging. Defaults to `false`
+
+**Returns:** Path to the created directory
+
 ### `downloadToResponse(options): Promise<Response>`
 
 Downloads a StackBlitz project and returns it as a Web Response (universal).

app/index.html

@@ -79,8 +79,10 @@ <h3>CLI</h3>
                 </button>
               </div>
               <pre><code id="cli-code"><span class="comment"># download to my-project.zip</span>
+npx stackblitz-zip https://stackblitz.com/edit/nuxtblitz my-project.zip
 
-npx stackblitz-zip https://stackblitz.com/edit/nuxtblitz my-project.zip</code></pre>
+<span class="comment"># or clone to a directory</span>
+npx stackblitz-clone https://stackblitz.com/edit/nuxtblitz my-project</code></pre>
             </div>
 
             <div class="code-sample">
@@ -96,9 +98,11 @@ <h3>Programmatic</h3>
                   <span>copy</span>
                 </button>
               </div>
-              <pre><code id="programmatic-code"><span class="keyword">import</span> { <span class="function">downloadProject</span> } <span class="keyword">from</span> <span class="string">'stackblitz-zip'</span>
+              <pre><code id="programmatic-code"><span class="keyword">import</span> { <span class="function">downloadToFile</span>, <span class="function">cloneProject</span> } <span class="keyword">from</span> <span class="string">'stackblitz-zip'</span>
 
-<span class="keyword">await</span> <span class="function">downloadProject</span>(<span class="string">'nuxtblitz'</span>, <span class="string">'output.zip'</span>)</code></pre>
+<span class="keyword">await</span> <span class="function">downloadToFile</span>({ <span class="string">projectId</span>: <span class="string">'nuxtblitz'</span>, <span class="string">outputPath</span>: <span class="string">'out.zip'</span> })
+
+<span class="keyword">await</span> <span class="function">cloneProject</span>({ <span class="string">projectId</span>: <span class="string">'nuxtblitz'</span>, <span class="string">outputPath</span>: <span class="string">'./out'</span> })</code></pre>
             </div>
           </div>
         </div>

app/server.ts

@@ -6,6 +6,12 @@ export default defineHandler(async (event) => {
   if (pathname === '/')
     return // render index.html
 
+  // Check if this is a clone request (just redirect to regular download for now)
+  if (pathname.startsWith('/clone/')) {
+    const cleanPath = pathname.replace(/^\/clone\//, '')
+    return Response.redirect(`https://stackblitz.zip/${cleanPath}`, 302)
+  }
+
   // Convert stackblitz.zip URL to stackblitz.com URL
   const stackblitzUrl = `https://stackblitz.com/${pathname.replace(/^\/|\.zip$/g, '')}`
 

package.json

@@ -20,7 +20,8 @@
     }
   },
   "bin": {
-    "stackblitz-zip": "./dist/cli.mjs"
+    "stackblitz-zip": "./dist/cli/zip.mjs",
+    "stackblitz-clone": "./dist/cli/clone.mjs"
   },
   "files": [
     "dist"
@@ -32,6 +33,7 @@
     "prepare": "simple-git-hooks",
     "prepack": "pnpm build",
     "prepublishOnly": "pnpm lint && pnpm test",
+    "publish:alias": "node scripts/publish-alias.js",
     "release": "bumpp",
     "test": "pnpm test:unit && pnpm test:types",
     "test:unit": "vitest",

scripts/publish-alias.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+
+/**
+ * Publish the package as 'stackblitz-clone' alias
+ * Run this after publishing 'stackblitz-zip'
+ */
+
+import { execSync } from 'node:child_process'
+import { readFile, writeFile } from 'node:fs/promises'
+import { resolve } from 'node:path'
+import process from 'node:process'
+
+const packageJsonPath = resolve(process.cwd(), 'package.json')
+
+async function main() {
+  console.log('📦 Publishing as stackblitz-clone...\n')
+
+  // Read current package.json
+  const originalContent = await readFile(packageJsonPath, 'utf-8')
+  const pkg = JSON.parse(originalContent)
+  const originalName = pkg.name
+
+  if (originalName !== 'stackblitz-zip') {
+    console.error('❌ Error: Expected package name to be "stackblitz-zip"')
+    process.exit(1)
+  }
+
+  try {
+    // Update package name
+    pkg.name = 'stackblitz-clone'
+    pkg.description = 'Clone StackBlitz projects to local directories'
+    await writeFile(packageJsonPath, `${JSON.stringify(pkg, null, 2)}\n`)
+    console.log('✓ Updated package.json name to "stackblitz-clone"')
+
+    // Publish
+    console.log('\n📤 Publishing to npm...')
+    execSync('pnpm publish --no-git-checks', { stdio: 'inherit' })
+    console.log('\n✓ Published stackblitz-clone successfully!')
+  }
+  catch (error) {
+    console.error('\n❌ Error during publishing:', error)
+  }
+  finally {
+    // Restore original package.json
+    await writeFile(packageJsonPath, originalContent)
+    console.log('✓ Restored package.json to "stackblitz-zip"')
+  }
+}
+
+main().catch(console.error)

src/cli.ts src/cli/clone.tssrc/cli.ts renamed to src/cli/clone.ts

@@ -1,25 +1,25 @@
 #!/usr/bin/env node
 
 import process from 'node:process'
-import { downloadToFile, parseUrl } from './download'
+import { cloneProject, parseUrl } from '../download'
 
 async function main() {
   const args = process.argv.slice(2)
 
   if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
     console.log(`
-StackBlitz Project Downloader
+StackBlitz Project Clone Tool
 
 Usage:
-  stackblitz-zip <url> [output-path]
+  stackblitz-clone <url> [output-path]
 
 Arguments:
   url          StackBlitz project URL (e.g., https://stackblitz.com/edit/nuxt-starter-k7spa3r4)
-  output-path  Optional path for the output zip file (defaults to <project-id>.zip)
+  output-path  Optional path for the output directory (defaults to <project-id>/)
 
 Examples:
-  stackblitz-zip https://stackblitz.com/edit/nuxt-starter-k7spa3r4
-  stackblitz-zip https://stackblitz.com/edit/nuxt-starter-k7spa3r4 my-project.zip
+  stackblitz-clone https://stackblitz.com/edit/nuxt-starter-k7spa3r4
+  stackblitz-clone https://stackblitz.com/edit/nuxt-starter-k7spa3r4 ./my-project
 `)
     process.exit(0)
   }
@@ -29,7 +29,7 @@ Examples:
 
   try {
     const projectId = parseUrl(url)
-    await downloadToFile({ projectId, outputPath, verbose: true })
+    await cloneProject({ projectId, outputPath, verbose: true })
   }
   catch (error) {
     console.error('❌ Error:', error instanceof Error ? error.message : error)

src/cli/zip.ts

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+
+import process from 'node:process'
+import { cloneProject, downloadToFile, parseUrl } from '../download'
+
+async function main() {
+  const args = process.argv.slice(2)
+
+  if (args.length === 0 || args.includes('--help') || args.includes('-h')) {
+    console.log(`
+StackBlitz Project Downloader
+
+Usage:
+  stackblitz-zip <url> [output-path]              Download as zip file
+  stackblitz-zip clone <url> [output-path]        Clone to directory
+
+Arguments:
+  url          StackBlitz project URL (e.g., https://stackblitz.com/edit/nuxt-starter-k7spa3r4)
+  output-path  Optional path for the output (defaults to <project-id>.zip or <project-id>/)
+
+Examples:
+  stackblitz-zip https://stackblitz.com/edit/nuxt-starter-k7spa3r4
+  stackblitz-zip https://stackblitz.com/edit/nuxt-starter-k7spa3r4 my-project.zip
+  stackblitz-zip clone https://stackblitz.com/edit/nuxt-starter-k7spa3r4
+  stackblitz-zip clone https://stackblitz.com/edit/nuxt-starter-k7spa3r4 ./my-project
+`)
+    process.exit(0)
+  }
+
+  const isClone = args[0] === 'clone'
+  const url = isClone ? args[1]! : args[0]!
+  const outputPath = isClone ? args[2] : args[1]
+
+  try {
+    const projectId = parseUrl(url)
+
+    if (isClone) {
+      await cloneProject({ projectId, outputPath, verbose: true })
+    }
+    else {
+      await downloadToFile({ projectId, outputPath, verbose: true })
+    }
+  }
+  catch (error) {
+    console.error('❌ Error:', error instanceof Error ? error.message : error)
+    process.exit(1)
+  }
+}
+
+main()