Skip to content

Commit b47a251

Browse files
author
cursor-ide
committed
feat: initialize VSCode extension scaffolding toolkit with templates and core utilities
0 parents  commit b47a251

21 files changed

Lines changed: 1299 additions & 0 deletions

File tree

‎.github/workflows/create.yml‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
name: Build and Test @vsce/create
2+
3+
on:
4+
push:
5+
branches: [ main ]
6+
paths:
7+
- '**'
8+
- '.github/workflows/create.yml'
9+
pull_request:
10+
branches: [ main ]
11+
workflow_dispatch: # Allow manual triggering
12+
13+
jobs:
14+
test:
15+
runs-on: ubuntu-latest
16+
permissions:
17+
contents: write # Needed for committing fmt changes
18+
id-token: write # Needed for JSR publishing
19+
20+
steps:
21+
- uses: actions/checkout@v4
22+
with:
23+
fetch-depth: 0
24+
25+
- uses: denoland/setup-deno@v2
26+
with:
27+
deno-version: v2.x
28+
29+
- name: Regenerate lockfile if needed
30+
run: |
31+
if ! deno cache --check mod.ts 2>/dev/null; then
32+
echo "Regenerating lockfile due to version mismatch"
33+
rm -f deno.lock
34+
deno cache mod.ts
35+
fi
36+
37+
- name: Type check
38+
run: deno task check
39+
40+
- name: Lint code
41+
run: deno task lint
42+
43+
- name: Format code
44+
run: deno task fmt
45+
46+
- name: Commit formatting changes if any
47+
run: |
48+
if [[ -n "$(git status --porcelain)" ]]; then
49+
git config user.name "github-actions[bot]"
50+
git config user.email "github-actions[bot]@users.noreply.github.com"
51+
git add -A
52+
git commit -m "chore: auto-format code"
53+
fi
54+
55+
- name: Run tests
56+
run: deno task test
57+
58+
- name: Validate JSR package
59+
run: deno task publish-dry
60+
61+
- name: Commit changes if any
62+
run: |
63+
if [[ -n "$(git status --porcelain)" ]]; then
64+
git config user.name "github-actions[bot]"
65+
git config user.email "github-actions[bot]@users.noreply.github.com"
66+
git add -A
67+
VERSION=$(jq -r .version jsr.json)
68+
git commit -m "chore: sync create → v$VERSION"
69+
git push origin HEAD
70+
else
71+
echo "No changes to commit."
72+
fi
73+
74+
- name: Publish to JSR
75+
if: success() && github.ref == 'refs/heads/main'
76+
run: npx jsr publish

‎.gitignore‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Deno
2+
deno.lock
3+
.deno/
4+
5+
# IDE
6+
.vscode/
7+
.idea/
8+
9+
# OS
10+
.DS_Store
11+
Thumbs.db
12+
13+
# Logs
14+
*.log

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025 @typed/vscode contributors
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 248 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,248 @@
1+
# `@vsce/create`
2+
3+
> 🦕 The **Deno-native** scaffolding tool for modern, dual-runtime VS Code extensions
4+
5+
[![JSR Scope](https://jsr.io/badges/@vsce)](https://jsr.io/@vsce)
6+
[![JSR](https://jsr.io/badges/@vsce/create)](https://jsr.io/@vsce/create)
7+
[![JSR Score](https://jsr.io/badges/@vsce/create/score)](https://jsr.io/@vsce/create/score)
8+
[![GitHub CI](https://img.shields.io/github/actions/workflow/status/cursor-ide/vsce-create/update.yml?branch=main&label=sync)](https://github.com/cursor-ide/vsce-create/actions/workflows/update.yml)
9+
[![Last Updated](https://img.shields.io/github/last-commit/cursor-ide/vsce-create?label=last%20synced)](https://github.com/cursor-ide/vsce-create/commits/main)
10+
[![License](https://img.shields.io/github/license/cursor-ide/vsce-create)](./LICENSE)
11+
12+
`@vsce/create` bootstraps **Deno-first**, **web-compatible** VS Code extensions in seconds. Each project it generates is ready to build with [`@vsce/bundler`](https://jsr.io/@vsce/bundler) and ships with type-safe VS Code APIs via [`@typed/vscode`](https://jsr.io/@typed/vscode).
13+
14+
> **Heads-up!** `@vsce/create` is the low-level *scaffolding engine* used internally by [`@vsce/cli`](https://jsr.io/@vsce/cli) — our all-in-one, fully-featured development suite. If you want the entire toolchain (project generation, dev server, bundling, testing, publishing) in one command, install **`@vsce/cli`** instead.
15+
16+
---
17+
18+
## ✨ Features
19+
20+
| Category | Details |
21+
|----------|---------|
22+
| 🦕 **Deno-Native** | No Node.js toolchain required—scaffolds projects you can run & build with Deno only. |
23+
| 🌐 **Dual Runtime** | Templates target both Desktop and Web extension hosts out-of-the-box (`extensionKind: ["workspace", "web"]`). |
24+
| 🏗️ **Rich Templates** | `basic`, `treeview`, `webview`, and `language-server` templates plus shared utilities. |
25+
| 📦 **Bundler-Ready** | Generates a `scripts/build.ts` that calls `@vsce/bundler` for a single-file, web-safe bundle. |
26+
| 🔧 **VS Code Tasks** | Emits `.vscode/tasks.json` & `.vscode/launch.json` for one-click build, test & debug. |
27+
| ✅ **Strict Types** | Uses `@typed/vscode` definitions with full TypeScript `--strict` compliance. |
28+
29+
---
30+
31+
## 📥 Installation
32+
33+
```bash
34+
# Add to your Deno project (recommended)
35+
deno add @vsce/create
36+
```
37+
38+
or run directly without installation:
39+
40+
```bash
41+
deno run -A jsr:@vsce/create@latest init my-extension
42+
```
43+
44+
> `@vsce/create` targets **Deno ≥1.44** and **VS Code ≥1.90**.
45+
46+
---
47+
48+
## 🚀 Quick Start
49+
50+
```bash
51+
# Scaffold a Tree View extension
52+
deno run -A jsr:@vsce/create init my-treeview --template treeview
53+
cd my-treeview
54+
55+
# Build the extension (outputs dist/extension.js)
56+
deno task build
57+
58+
# Test everything
59+
deno task test
60+
```
61+
62+
Resulting structure (example `treeview`):
63+
64+
```text
65+
my-treeview/
66+
├── README.md # template-specific doc
67+
├── deno.json # import map + tasks + lint/fmt
68+
├── jsr.json # JSR package meta
69+
├── package.json # VS Code extension manifest
70+
├── scripts/
71+
│ └── build.ts # calls @vsce/bundler
72+
├── src/
73+
│ └── extension.ts # your entry point
74+
└── .vscode/
75+
├── extensions.json # recommended VS Code extensions
76+
├── tasks.json # build / test tasks
77+
└── launch.json # debug configuration
78+
```
79+
80+
---
81+
82+
## 🗂️ Available Templates
83+
84+
| Template | Description |
85+
|----------|-------------|
86+
| `basic` | Minimal “Hello World” command—perfect seed for small utilities. |
87+
| `treeview` | Demonstrates `TreeDataProvider`, custom view registration and refresh command. |
88+
| `webview` | Shows how to create a Webview panel with static HTML content. |
89+
| `language-server` | Runs a minimal language server in a Web Worker using `vscode-languageclient/browser`. |
90+
91+
---
92+
93+
## 🔄 Development Workflow
94+
95+
1. **Start coding** inside `src/extension.ts` (or additional modules).
96+
VS Code + the [Deno extension](https://marketplace.visualstudio.com/items?itemName=denoland.vscode-deno) give you instant type-checking and IntelliSense.
97+
2. **Press `F5`** to run the *Run Extension* launch target (uses Deno to execute `scripts/build.ts`).
98+
3. **Run tests** with `deno task test` (generated for you).
99+
All templates include example tests you can extend.
100+
4. **Bundle** with `deno task build` for production. The output `dist/extension.js` works for both desktop and web versions of VS Code.
101+
102+
---
103+
104+
### Web Extension Support
105+
106+
#### Why Web Extensions?
107+
108+
This package is optimized for the **VSCode Web Extensions** runtime as our **pragmatic path to bringing VSCode extension development to Deno**. While our ideal would be full parity with the Node.js extension development environment, the web extension runtime represents the best available approach given current VSCode architecture limitations.
109+
110+
**The Reality:**
111+
112+
- 🎯 **Goal**: Enable Deno-native VSCode extension development
113+
- ⚠️ **Challenge**: VSCode's extension host is deeply integrated with Node.js
114+
- ✅ **Solution**: Leverage the web extension runtime for Deno compatibility
115+
- 🪄 **Future**: Working toward fuller Node.js runtime parity as the ecosystem evolves
116+
117+
#### Universal Compatibility
118+
119+
The web extension runtime enables you to create extensions that run **everywhere** - both desktop VSCode and web-based environments (vscode.dev, github.dev, GitHub Codespaces):
120+
121+
```typescript
122+
import * as vscode from "@typed/vscode";
123+
124+
// Web extensions run on BOTH desktop and web VSCode
125+
export function activate(context: vscode.ExtensionContext): void {
126+
// Full VSCode API support: TreeView, Commands, Language Features, etc.
127+
const provider = new MyTreeDataProvider();
128+
vscode.window.createTreeView('myView', { treeDataProvider: provider });
129+
130+
// Limitation: Node.js APIs are not available (browser sandbox restrictions)
131+
// However, we can use Deno's web API's as a drop-in replacement for some Node.js APIs
132+
// The extension works identically on desktop and web!
133+
}
134+
```
135+
136+
**Key Benefits:**
137+
138+
- ✅ **Universal compatibility** - One extension runs on desktop AND web VSCode
139+
- ✅ **Full VSCode API access** - Commands, UI, language features, etc.
140+
- ✅ **Modern deployment** - Works in vscode.dev, github.dev, Codespaces
141+
- ⚠️ **Browser limitations** - No Node.js/filesystem APIs (applies to web runtime only)
142+
143+
## 🚧 Deno VSCode Extension Ecosystem (WIP) 🚧
144+
145+
`@typed/vscode` is part of a complete ecosystem for Deno-based VSCode extension development. Explore these complementary packages:
146+
147+
### 🛠️ Development Tools
148+
149+
**[@vsce/cli](https://jsr.io/@vsce/cli)** - Command-line tools for Deno VSCode extensions
150+
151+
```bash
152+
deno add @vsce/cli
153+
```
154+
155+
- Project scaffolding and templates
156+
- Development server with hot reload
157+
- Build and packaging utilities
158+
- Extension testing and validation
159+
160+
**[@vsce/create](https://jsr.io/@vsce/create)** - Project generator for new extensions
161+
162+
```bash
163+
deno add @vsce/create
164+
```
165+
166+
- Interactive project setup
167+
- Multiple template options (basic, language server, tree view, etc.)
168+
- Deno-optimized project structure
169+
- Best practices and conventions built-in
170+
171+
### 🔧 Build and Bundle
172+
173+
**[@vsce/bundler](https://jsr.io/@vsce/bundler)** - Web extension bundler for Deno
174+
175+
```bash
176+
deno add @vsce/bundler
177+
```
178+
179+
- Bundle Deno code for VSCode web extensions
180+
- Tree shaking and optimization
181+
- Source map support
182+
- Multi-target builds (desktop + web)
183+
184+
### 🧪 Testing Framework
185+
186+
**[@vsce/testing](https://jsr.io/@vsce/testing)** - Testing utilities for VSCode extensions
187+
188+
```bash
189+
deno add @vsce/testing
190+
```
191+
192+
- Mock VSCode APIs for unit testing
193+
- Extension host simulation
194+
- Language server testing utilities
195+
- TreeView and UI component testing
196+
197+
### 📚 Complete Example
198+
199+
```typescript
200+
// extension.ts - Built with the full @vsce ecosystem
201+
import * as vscode from "@typed/vscode";
202+
import { createLanguageServer } from "@vsce/cli";
203+
import { MockExtensionContext } from "@vsce/testing";
204+
205+
export async function activate(context: vscode.ExtensionContext): Promise<void> {
206+
// Full ecosystem integration example
207+
const server = await createLanguageServer({
208+
name: 'my-language-server',
209+
languages: ['typescript', 'javascript']
210+
});
211+
212+
context.subscriptions.push(
213+
vscode.languages.registerHoverProvider(['typescript'], server),
214+
vscode.languages.registerCompletionItemProvider(['typescript'], server)
215+
);
216+
}
217+
```
218+
219+
## Runtime Compatibility
220+
221+
| Environment | Support | Notes |
222+
|-------------|---------|-------|
223+
| **VSCode Desktop** | ✅ Full | All APIs available |
224+
| **VSCode Web** | ✅ Most APIs | No Node.js/filesystem APIs |
225+
| **Deno Runtime** | ✅ Type-checking | For development and testing |
226+
| **GitHub Codespaces** | ✅ Full | Web + server APIs |
227+
| **vscode.dev** | ✅ Web APIs | Browser-based development |
228+
229+
---
230+
231+
## 📚 Docs & Resources
232+
233+
- VS Code Extension API: <https://code.visualstudio.com/api>
234+
- VS Code Web Extensions Guide: <https://code.visualstudio.com/api/extension-guides/web-extensions>
235+
- Deno Runtime Documentation: <https://docs.deno.com>
236+
- JSR Package Registry: <https://jsr.io>
237+
238+
---
239+
240+
## License
241+
242+
MIT License - see [LICENSE](./LICENSE) for details.
243+
244+
---
245+
246+
**Happy coding with Deno + VSCode! 🦕⚡**
247+
248+
*Part of the [@vsce ecosystem](https://jsr.io/@vsce) for Deno-based VSCode extension development.*

0 commit comments

Comments
 (0)