58 | 59 | 60 | 61 | 62 | {#each $markers as marker} 63 |
Line {marker.startLineNumber}: 64 | {marker.message}
65 | {/each} 66 |58 | 59 | 60 | 61 | 62 | {#each $markers as marker} 63 |
66 |
67 | Now, **refresh the browser**. When the playground reeoads, a new tab with your plugin should appear! 🎉
68 |
69 | 
70 |
71 | ## Props
72 |
73 | The TypeScript Playground Plugin API provides lifecycle methods that are used to interact with the playground. This library uses a combination of [writable store objects](https://svelte.dev/tutorial/writable-stores) and functions to provide the values and methods provided by these lifecycle methods to the Svelte app via props. The following props are provided to your Svelte app:
74 |
75 | ### **code**
76 |
77 | *Writable store*
78 |
79 | ```typescript
80 | string
81 | ```
82 |
83 | > Although this is writable store value, you don't want to write to it. See `setCode` and `formatCode` below.
84 |
85 | The current code in the Monaco editor. This value updates on change to the Monaco editor with optional debouncing. Uses `sandbox.getText()`.
86 |
87 | ### **setCode**
88 |
89 | *function*
90 |
91 | ```typescript
92 | (code: string, options: {format: boolean}) => void
93 | ```
94 |
95 | Set the code in the Monaco editor with optional formatting. Uses `sandbox.setText()`.
96 |
97 | ### **formatCode**
98 |
99 | *function*
100 |
101 | ```typescript
102 | () => void
103 | ```
104 |
105 | Format the code in the Monaco editor. Alias for `sandbox.editor.getAction("editor.action.formatDocument").run()`.
106 |
107 | ### **markers**
108 |
109 | *Readable store*
110 |
111 | ```typescript
112 | IMarker[]
113 | ```
114 |
115 | Alias for `sandbox.monaco.editor.getModelMarkers({})`. Kept in sync via `sandbox.editor.onDidChangeModelDecorations`.
116 |
117 | Here is the [type definition](https://github.com/Microsoft/monaco-editor/blob/master/monaco.d.ts#L875) for `IMarker`:
118 |
119 | ```typescript
120 | interface IMarker {
121 | owner: string;
122 | resource: Uri;
123 | severity: MarkerSeverity;
124 | code?:
125 | | string
126 | | {
127 | value: string;
128 | link: Uri;
129 | };
130 | message: string;
131 | source?: string;
132 | startLineNumber: number;
133 | startColumn: number;
134 | endLineNumber: number;
135 | endColumn: number;
136 | relatedInformation?: IRelatedInformation[];
137 | tags?: MarkerTag[];
138 | }
139 | ```
140 |
141 | ### **setDebounce**
142 |
143 | *function*
144 |
145 | ```typescript
146 | (debounce: boolean) => void
147 | ```
148 | Optionally debounce the `modelChange` event from the Plugin API. Per the Plugin docs, this is run on a delay and may not fire on every keystroke. The `code` prop will be updated accordingly. Default is `true`.
149 |
150 | ### **sandbox**
151 |
152 | *object*
153 |
154 | ```typescript
155 | Sandbox
156 | ```
157 |
158 | A DOM library for interacting with TypeScript and JavaScript code, which powers the heart of the TypeScript playground. This object provides several properties and methods to interact with the playground. See all of the available types in `src/plugin/vendor/sandbox.d.ts` and read more about the sandbox at [http://www.typescriptlang.org/v2/dev/sandbox/](http://www.typescriptlang.org/v2/dev/sandbox/).
159 |
160 | ### **model**
161 |
162 | *Writable store*
163 |
164 | ```typescript
165 | Model
166 | ```
167 |
168 | The model is an object which Monaco uses to keep track of text in the editor. You can find the full type definition at `node_modules/monaco-editor/esm/vs/editor/editor.api.d.ts`. Although this is a writable store, you should not overwrite it.
169 |
170 | ### **container**
171 |
172 | ```typescript
173 | HTMLDivElement
174 | ```
175 |
176 | The `div` element that wraps the entire sidebar. The Svelte app is mounted to this element. Any style changes to this element will affect the entire sidebar.
177 |
178 | ### **showModal**
179 |
180 | *function*
181 |
182 | ```typescript
183 | (code: string, subtitle?: string, links?: string[]) => void
184 | ```
185 | From `window.playground.ui` - This function accepts three arguments (code, subtitle, and links) and opens a model with the values you provide.
186 |
187 | ### **flashInfo**
188 |
189 | *function*
190 |
191 | ```typescript
192 | (message: string) => void
193 | ```
194 | From `window.playground.ui` - This function accepts one argument (message) and and flashes a quick message in the center of the screen.
195 |
196 | ### **utils**
197 |
198 | *object*
199 |
200 | ```typescript
201 | {
202 | el: (str: string, el: string, container: Element) => void;,
203 | requireURL: (path: string) => string;,
204 | createASTTree: (node: Node) => HTMLDivElement;
205 | }
206 | ```
207 | An object that contains three additional config options and functionality. `el`, `requireURL`, and `createASTTree`. See `src/plugin/vendor/pluginUtils.d.ts` for more information.
208 |
209 | 210 | 211 | You can access them in `App.svelte` like so: 212 | 213 | ```html 214 | 227 | ``` 228 | 229 | 230 | ## Styling your plugin 231 | 232 | Style you Svelte components as normal. All styles defined in your Svelte components are automatically injected into the page at render time. You can read more about styling Svelte components at [https://svelte.dev/docs#style](https://svelte.dev/docs#style). 233 | 234 | You can also apply styles to the `container` element. Be cautious as this will affect all tabs in the sidebar. 235 | 236 | ## More about TypeScript Playground Plugins 237 | 238 | [Official Playground Plugin Documentation](https://www.typescriptlang.org/v2/dev/playground-plugins/) 239 | 240 | You can create a plugin (without Svelte) from the official plugin template: 241 | 242 | ```sh 243 | npm init typescript-playground-plugin playground-my-plugin 244 | ``` 245 | 246 | For convenience, this repo contains the `CONTRIBUTING.md` file included in the official plugin template. This document contains useful information about how to work with the plugins. 247 | 248 | The `src/vendor` directory contains all of the TypeScript type definitions for the TypeScript Playground Plugin API. This is the best place to find the various config options, properties, and methods that are available. 249 | 250 | ### Need inspiration? 251 | 252 | [Orta](https://github.com/orta) created a really cool plugin that lets you create presentations in the TypeScript playground using Reveal.js. You can check it out here: 253 | 254 | [https://github.com/orta/playground-slides](https://github.com/orta/playground-slides) 255 | 256 | He also offered these plugin ideas in [this](https://github.com/microsoft/TypeScript-Website/issues/221) issue. 257 | 258 | - An LSP-ish Playground where you can make see the response to specific calls 259 | - An English explainer which explains a complex TS type 260 | - Convert TS dts -> Flow interfaces(flowgen) 261 | - Run tutorials in the playground against live code as a learning tool 262 | - AST Viewer 263 | - ts-query runner 264 | - codemod runner 265 | - Highlight TS vs JS (or type vs value) parts of some code code 266 | - Show all used types in a file 267 | - Show dts files in the current workspace 268 | - Edit an ambient dts file -------------------------------------------------------------------------------- /src/vendor/sandbox.d.ts: -------------------------------------------------------------------------------- 1 | import { TypeScriptWorker } from "./tsWorker";// import { TypeScriptWorker } from './tsWorker'; 2 | // import lzstring from './vendor/lzstring.min'; 3 | 4 | import * as tsvfs from './typescript-vfs'; 5 | declare type CompilerOptions = import('monaco-editor').languages.typescript.CompilerOptions; 6 | /** 7 | * These are settings for the playground which are the equivalent to props in React 8 | * any changes to it should require a new setup of the playground 9 | */ 10 | export declare type PlaygroundConfig = { 11 | /** The default source code for the playground */ 12 | text: string; 13 | /** Should it run the ts or js IDE services */ 14 | useJavaScript: boolean; 15 | /** Compiler options which are automatically just forwarded on */ 16 | compilerOptions: CompilerOptions; 17 | /** Optional monaco settings overrides */ 18 | monacoSettings?: import('monaco-editor').editor.IEditorOptions; 19 | /** Acquire types via type acquisition */ 20 | acquireTypes: boolean; 21 | /** Support twoslash compiler options */ 22 | supportTwoslashCompilerOptions: boolean; 23 | /** Get the text via query params and local storage, useful when the editor is the main experience */ 24 | suppressAutomaticallyGettingDefaultText?: true; 25 | /** Suppress setting compiler options from the compiler flags from query params */ 26 | suppressAutomaticallyGettingCompilerFlags?: true; 27 | /** Logging system */ 28 | logger: { 29 | log: (...args: any[]) => void; 30 | error: (...args: any[]) => void; 31 | }; 32 | } & ({ 33 | domID: string; 34 | } | { 35 | elementToAppend: HTMLElement; 36 | }); 37 | /** The default settings which we apply a partial over */ 38 | export declare function defaultPlaygroundSettings(): { 39 | /** The default source code for the playground */ 40 | text: string; 41 | /** Should it run the ts or js IDE services */ 42 | useJavaScript: boolean; 43 | /** Compiler options which are automatically just forwarded on */ 44 | compilerOptions: import("monaco-editor").languages.typescript.CompilerOptions; 45 | /** Optional monaco settings overrides */ 46 | monacoSettings?: import("monaco-editor").editor.IEditorOptions | undefined; 47 | /** Acquire types via type acquisition */ 48 | acquireTypes: boolean; 49 | /** Support twoslash compiler options */ 50 | supportTwoslashCompilerOptions: boolean; 51 | /** Get the text via query params and local storage, useful when the editor is the main experience */ 52 | suppressAutomaticallyGettingDefaultText?: true | undefined; 53 | /** Suppress setting compiler options from the compiler flags from query params */ 54 | suppressAutomaticallyGettingCompilerFlags?: true | undefined; 55 | /** Logging system */ 56 | logger: { 57 | log: (...args: any[]) => void; 58 | error: (...args: any[]) => void; 59 | }; 60 | } & { 61 | domID: string; 62 | }; 63 | /** Creates a sandbox editor, and returns a set of useful functions and the editor */ 64 | export declare const createTypeScriptSandbox: (partialConfig: Partial<{ 65 | /** The default source code for the playground */ 66 | text: string; 67 | /** Should it run the ts or js IDE services */ 68 | useJavaScript: boolean; 69 | /** Compiler options which are automatically just forwarded on */ 70 | compilerOptions: import("monaco-editor").languages.typescript.CompilerOptions; 71 | /** Optional monaco settings overrides */ 72 | monacoSettings?: import("monaco-editor").editor.IEditorOptions | undefined; 73 | /** Acquire types via type acquisition */ 74 | acquireTypes: boolean; 75 | /** Support twoslash compiler options */ 76 | supportTwoslashCompilerOptions: boolean; 77 | /** Get the text via query params and local storage, useful when the editor is the main experience */ 78 | suppressAutomaticallyGettingDefaultText?: true | undefined; 79 | /** Suppress setting compiler options from the compiler flags from query params */ 80 | suppressAutomaticallyGettingCompilerFlags?: true | undefined; 81 | /** Logging system */ 82 | logger: { 83 | log: (...args: any[]) => void; 84 | error: (...args: any[]) => void; 85 | }; 86 | } & { 87 | domID: string; 88 | }> | Partial<{ 89 | /** The default source code for the playground */ 90 | text: string; 91 | /** Should it run the ts or js IDE services */ 92 | useJavaScript: boolean; 93 | /** Compiler options which are automatically just forwarded on */ 94 | compilerOptions: import("monaco-editor").languages.typescript.CompilerOptions; 95 | /** Optional monaco settings overrides */ 96 | monacoSettings?: import("monaco-editor").editor.IEditorOptions | undefined; 97 | /** Acquire types via type acquisition */ 98 | acquireTypes: boolean; 99 | /** Support twoslash compiler options */ 100 | supportTwoslashCompilerOptions: boolean; 101 | /** Get the text via query params and local storage, useful when the editor is the main experience */ 102 | suppressAutomaticallyGettingDefaultText?: true | undefined; 103 | /** Suppress setting compiler options from the compiler flags from query params */ 104 | suppressAutomaticallyGettingCompilerFlags?: true | undefined; 105 | /** Logging system */ 106 | logger: { 107 | log: (...args: any[]) => void; 108 | error: (...args: any[]) => void; 109 | }; 110 | } & { 111 | elementToAppend: HTMLElement; 112 | }>, monaco: typeof import("monaco-editor"), ts: typeof import("typescript")) => { 113 | /** The same config you passed in */ 114 | config: { 115 | text: string; 116 | useJavaScript: boolean; 117 | compilerOptions: import("monaco-editor").languages.typescript.CompilerOptions; 118 | monacoSettings?: import("monaco-editor").editor.IEditorOptions | undefined; 119 | acquireTypes: boolean; 120 | supportTwoslashCompilerOptions: boolean; 121 | suppressAutomaticallyGettingDefaultText?: true | undefined; 122 | suppressAutomaticallyGettingCompilerFlags?: true | undefined; 123 | logger: { 124 | log: (...args: any[]) => void; 125 | error: (...args: any[]) => void; 126 | }; 127 | domID: string; 128 | }; 129 | /** A list of TypeScript versions you can use with the TypeScript sandbox */ 130 | supportedVersions: readonly ["2.4.1", "2.7.2", "2.8.1", "3.0.1", "3.1.6", "3.3.3", "3.5.1", "3.6.3", "3.7.5", "3.8.2"]; 131 | /** The monaco editor instance */ 132 | editor: import("monaco-editor").editor.IStandaloneCodeEditor; 133 | /** Either "typescript" or "javascript" depending on your config */ 134 | language: string; 135 | /** The outer monaco module, the result of require("monaco-editor") */ 136 | monaco: typeof import("monaco-editor"); 137 | /** Gets a monaco-typescript worker, this will give you access to a language server. Note: prefer this for language server work because it happens on a webworker . */ 138 | getWorkerProcess: () => Promise