Building an Instant "Try Now" Experience: Our StackBlitz Integration Journey

The Challenge: Friction Kills Adoption

We had a problem. Developers landing on clodo.dev were intrigued by our enterprise-grade framework for Cloudflare Workers, but there was a massive gap between interest and actually trying it.

The traditional developer experience looked like this:

1. Clone repository
2. Install Node.js and npm
3. Run npm install
4. Configure Cloudflare credentials
5. Read documentation to understand setup
6. Debug inevitable environment issues
7. Finally write first line of code (maybe)

Time to first "Hello World": 30-60 minutes minimum.

For a framework targeting rapid development, this was unacceptable. We needed instant gratification.

The Vision: One-Click to Code

What if developers could start coding in 60 seconds? No installation, no configuration, no friction.

"Show, don't tell. Let them experience the framework before they commit to installing it."

That's where StackBlitz came in. A browser-based IDE that could:

• ✅ Run Node.js directly in the browser
• ✅ Install npm packages automatically
• ✅ Fetch code from GitHub repos
• ✅ Provide instant feedback
• ✅ Zero setup required

Phase 1: The Simple Button (That Wasn't So Simple)

It started innocently enough. Add a "Try Now" button to the hero section:

<button onclick="window.open('https://stackblitz.com/github/tamylaa/clodo-starter-template')">
    🚀 Try Now - 1 Click
</button>

Easy, right? Click the button, StackBlitz opens, developer starts coding.

Problem #1: The Button Went Rogue

The button was navigating to /demo/ instead of opening StackBlitz. Hours of debugging revealed:

• Duplicate button elements in HTML (one visible, one hidden)
• Conflicting JavaScript event listeners
• Complex modal logic interfering with onclick handlers

Solution: Simplify ruthlessly. Remove all complexity, use a direct onclick handler with type="button" to prevent form submission behavior.

<button type="button" onclick="window.open('https://stackblitz.com/...', '_blank')">
    🚀 Try Now - 1 Click
</button>

Phase 2: The Silent Build Failure

Button fixed! But production wasn't updating. Commits pushed successfully, but the live site showed old code.

The Culprit: Broken Git Submodule

Our clodo-starter-template was tracked as a git submodule, but without a proper .gitmodules file. Git showed it as mode 160000 (submodule commit reference), causing Cloudflare Pages builds to fail silently. Read our full debugging guide for the technical details.

# Diagnosis
$ git ls-tree HEAD | grep clodo-starter-template
160000 commit 1c53a56... clodo-starter-template

# The fix
$ git rm --cached clodo-starter-template
$ echo "clodo-starter-template/" >> .gitignore
$ git add .gitignore
$ git commit -m "Fix: remove broken submodule reference"

Lesson learned: Git submodules need proper configuration or should be avoided. Separate repositories are often cleaner.

Phase 3: From Mock to Real Framework

Now StackBlitz opened correctly, but the demo was using mock code. We wanted developers to experience the real @tamyla/clodo-framework npm package.

The Transition to Real Package

Updated package.json:

{
  "name": "clodo-demo",
  "type": "module",
  "dependencies": {
    "@tamyla/clodo-framework": "^3.1.24"
  }
}

And .stackblitzrc to auto-install:

{
  "startCommand": "node index.js",
  "installDependencies": true,
  "nodeVersion": "18"
}

ESM vs CommonJS

Modern JavaScript uses ES Modules (ESM), not CommonJS. We converted:

// ❌ Old: CommonJS
const { createService } = require('@tamyla/clodo-framework');

// ✅ New: ESM
import { createService } from '@tamyla/clodo-framework';

Added "type": "module" to package.json to enable ESM throughout the demo.

Phase 4: The Cache Problem

Everything worked locally. Pushed to GitHub. But StackBlitz still showed the old mock code.

The issue: StackBlitz caches GitHub repositories aggressively for performance.

Cache-Busting Strategy

Instead of using the branch reference (which gets cached), we used the specific commit hash:

<!-- ❌ Cached version -->
https://stackblitz.com/github/tamylaa/clodo-starter-template

<!-- ✅ Cache-busted version -->
https://stackblitz.com/github/tamylaa/clodo-starter-template/tree/bedd21a

The commit hash (bedd21a) is immutable, so StackBlitz fetches the exact version we want.

The Final Implementation

Here's what we shipped:

1. The Button (index)

<button type="button" 
        id="try-live-btn" 
        class="btn btn-primary"
        onclick="window.open('https://stackblitz.com/github/tamylaa/clodo-starter-template/tree/bedd21a?file=index.js', '_blank')">
    <span>🚀 Try Now - 1 Click</span>
    <small>Instant coding environment</small>
</button>

2. The Demo Repository (clodo-starter-template)

package.json

{
  "name": "clodo-demo",
  "version": "1.0.0",
  "description": "Clodo Framework Instant Demo",
  "type": "module",
  "main": "index.js",
  "dependencies": {
    "@tamyla/clodo-framework": "^3.1.24"
  },
  "keywords": ["edge-computing", "cloudflare-workers", "serverless"]
}

index.js

// Import the real Clodo Framework from npm
import { createService } from '@tamyla/clodo-framework';

console.log('🚀 Clodo Framework Demo - Real Package!');
console.log('📦 Loading @tamyla/clodo-framework...');

// Demo service using real framework
const demoService = createService('demo', (request, env) => {
    const { method, url, headers = {} } = request;

    if (method === 'GET' && url.includes('/api/health')) {
        return {
            status: 200,
            message: 'Service is healthy!',
            timestamp: new Date().toISOString(),
            framework: 'Clodo Framework (Real)',
            version: '3.1.24'
        };
    }

    return {
        status: 200,
        message: 'Hello from Clodo Framework on the Edge!',
        timestamp: new Date().toISOString(),
        tip: 'Try editing this message!',
        userAgent: headers['user-agent'] || 'Unknown',
        method,
        url
    };
});

// Test the service
console.log('🧪 Testing service...');
demoService.handleRequest(
    { method: 'GET', url: '/api/demo', headers: { 'user-agent': 'StackBlitz/1.0' }},
    { NODE_ENV: 'demo' }
);

console.log('✅ Ready to code! Edit the service logic above.');

.stackblitzrc

{
  "startCommand": "node index.js",
  "installDependencies": true,
  "nodeVersion": "18"
}

The Results: From 30 Minutes to 60 Seconds

Learn more about the business impact in our 30x Faster Developer Onboarding analysis.

Key Takeaways

1. Simplicity wins. Remove complexity ruthlessly. A direct onclick handler beat complex modal systems.
2. Git submodules are tricky. Either configure them properly or avoid them. Silent failures are the worst.
3. Cache is both friend and foe. Use commit hashes for immutable references and cache-busting.
4. ESM is the future. Modern JavaScript should use import, not require().
5. Real packages matter. Mock code doesn't showcase the actual developer experience.
6. Test production. Local development can hide deployment issues.

Technical Decisions Worth Highlighting

Why StackBlitz Over CodeSandbox/Replit?

• StackBlitz runs Node.js natively in the browser using WebContainers
• Faster startup time (no container spin-up)
• Native npm install support
• Clean GitHub integration
• Free for open-source projects

Why Separate Repository for Demo?

• StackBlitz fetches entire repos - we wanted minimal demo, not full framework source
• Independent versioning and updates
• Cleaner demo experience without framework internals
• Can mark as GitHub template for easy forking

Why Commit Hash in URL?

• Immutable reference - specific version always works
• Bypasses StackBlitz cache
• Prevents breaking changes from affecting live demo
• Can update main branch while keeping stable demo

What's Next?

This is just the beginning. Future improvements we're considering:

• 📊 Analytics: Track how many developers click "Try Now" and actually run code
• 🎯 Guided tutorials: Interactive coding challenges in StackBlitz
• 🔀 Multiple templates: Different starting points (REST API, WebSocket service, D1 database integration)
• 💾 Save to GitHub: One-click fork to user's GitHub account
• 🚀 Deploy from StackBlitz: Direct deployment to Cloudflare Workers

Try It Yourself

The "Try Now" button is live on clodo.dev. Click it and you'll be coding with Clodo Framework in 60 seconds.

Want to build something similar for your project?

• 📦 View our demo repository
• 🎯 Try the live demo
• 📚 StackBlitz GitHub integration docs

Conclusion

Building a friction-free developer experience isn't just about good UX—it's about respecting developers' time. Every minute spent on setup is a minute not spent evaluating your framework.

By investing in instant gratification, we transformed our developer onboarding from a 30-60 minute commitment to a 60-second experiment. That's a 30-60x improvement in time-to-value.

The technical journey was messy—broken git submodules, caching issues, ESM vs CommonJS confusion—but the result is elegant: one button, one click, instant coding environment.

That's the kind of developer experience that converts curiosity into adoption.