Playground-browser-fs NPM

Playground Browser FS

The Playground Browser FS plugin provides an api on the global 'browserfs' for other plugins to consume. It uses a fork of BrowserFS to provide a custom build to provide a modern interface and helpers too interact with the playground.

preview

What it does

This plugin intialises BrowserFS with a MountableFileSystem. This allows other plugins to create and mount additional filesystems any given mount point. Using the createSystem and createCompilerHost factory functions will provide you with ts.System and ts.CompilerHost objects that can be used to invoke the typescript compiler using BrowserFS as file system.

When would you use it

The playground is powered by TypeScript VFS by default. This works great for single file cases and with a bit of knowledge of the source code implementing multiple file support is not that much extra work.

While playground-browser-fs is largely based on tsvfs it mimics a nodejs environment for the typescript compiler. For example createSystem and createCompilerHost will each respectively return a ts.System and ts.CompilerHost that will use the node module resolution algorithm to resolve modules with the help of browser-resolve.

Examples of plugins that use playground-browser-fs:

crickets

Ideas that could be implemented:

Compile a project consisting of multiple files and libraries
File Explorer and the option to edit multiple files
implement node_modules/ as a mirror to something like unpkg with the help of something like velcro.

Installation

create a typescript playground plugin

If you do not have a plugin yet follow these instructions.

install the plugin as a dependency

yarn add -D playground-browser-fs

install the BrowserFS fork as a dependency

# TODO: publish to npm
# TODO: drop this dependency as it is only used for .d.ts files
yarn add -D https://github.com/kevinramharak/BrowserFS

install @types/node as a dependency

# TODO: without these types typescript cannot find the shim types and wont compile, probably easier to extract the types and bundle them
yarn add -D @types/node

configure rollup to alias the module

// your config might look something like this:
export default rootFiles.map(name => {
  /** @type { import("rollup").RollupOptions } */
  const options = {
    input: `src/${name}`,
    external: ['typescript', 'playground-browser-fs'], // <-- add 'playground-browser-fs' to any exisiting externals
    output: {
      paths: {
        "typescript":"typescript-sandbox/index",
        "playground-browser-fs/api": "unpkg/playground-browser-fs/dist/api", // <-- add this entry,
      },
      name,
      dir: 'dist',
      format: 'amd',
    },
    plugins: [typescript({ tsconfig: 'tsconfig.json' }), commonjs(), node(), json()],
  }
  return options
})

The playground uses vscode-loader for AMD module looading. It uses the unpck/ prefix to fetch files from unkpg.

NOTE: !!! by using the above additions to your configuration the playground will fetch the playground-browser-fs plugin trough unpkg and thus share it with any other plugins that use it and thus removes the need to bundle the plugin and BrowserFS yourself, BrowserFS is written to work with a global instance and as such the playground plugin works the same.

API

BrowserFS

BrowserFS provides an interface similar to the fs module used in nodejs. In addition to the fs module BrowserFS provides the following shims with its require function:

NOTE: Keep in mind that these are shims of the API's and they will not be exact replica's.

import { fs, path, buffer, Buffer, process }  from 'playground-browser-fs';

The BrowserFS module itself can be accessed by accessing the browserfs.BrowserFS property:

import { BrowserFS } from 'playground-browser-fs';

It is recommended to use the browserfs api instead of the actual BrowserFS api whenever possible.

To make the BrowserFS easier to work with (and semi type safe) the following api is exposed:

import { createFileSystem, mountFileSystem, unmountFileSystem } from 'playground-browser-fs';

Those are defined with the following declarations:

// The FileSystemType maps to the backends at: https://jvilk.com/browserfs/2.0.0-beta/index.html#overview-of-backends
type FileSystemType = "AsyncMirror" | "FolderAdapter"| "InMemory" | "IndexedDB" | "LocalStorage" | "MountableFileSystem" | "WorkerFS" | "HTTPRequest" | "OverlayFS";

declare function createFileSystem<T extends FileSystemType>(config: FileSystemConfiguration<T>): Promise<FileSystem<T>>;

declare function mountFileSystem<T extends FileSystemType>(mountPoint: string, fs: FileSystem<T>): Promise<void>;

declare function unmountFileSystem(mountPoint: string): Promise<FileSystem<FileSystemType>>;

Create a ts.System and a ts.CompilerHost:

import ts from 'typescript'
import { createSystem, createCompilerHost, fs } from 'playground-browser-fs;
const { getCompilerOptions } = sandbox; // use the sandbox injected in your plugin

const compilerOptions = getCompilerOptions();
const system = createSystem(fs);
const host = createCompilerHost(system, compilerOptions, ts);

Check out the type definitions or take a look at the source code if you need more insight in how it works.