Thanks to the very powerful and flexible extensibility of VS Code, we can easily implement a VS Code extension that provides the custom File IO ability using FileSystemProvider API. There is an official demo named vscode-web-playground which shows how it is used.
On the other hand, GitHub provides the powerful REST API that can be used for a variety of tasks which includes reading directories and files for sure.
According to the above, obviously, the core concept of githubsurf is to implement a VS Code Extension (includes FileSystemProvider) using GitHub REST API.
github.surf is a purely static web app (because it really doesn't need a backend service, does it?). So we just deploy it on GitHub Pages now (the
gh-pages branch of this repository), and it is free. The service of github.surf could be reliable (GitHub is very reliable) because nobody needs to pay the web hosting bills.
Another thing that needs attention is Rate Limit:
For unauthenticated requests, the rate limit allows for up to 60 requests per hour. Unauthenticated requests are associated with the originating IP address, and not the user making requests.
For API requests using Basic Authentication or OAuth, you can make up to 5,000 requests per hour.
So, if you meet some problems when you use github.surf, even if you are using newer browsers, you could try to set a GitHub OAuth Token. Don't worry, we cannot see your token. It is only stored in your browser IndexedDB with VS Code Extension globalState API (Actually we don't have a server, do we?).
But this does not mean the token is absolutely safe, don't forget to clean it while you are using a device that doesn't belong to you.
As you see, running github.surf locally is not difficult. After cloning the repository, just run these commands:
yarnyarn watch # or yarn build, it may take minutes, wait please
Then, there will be a new directory named
dist generated in the project root. You can run
yarn serve in another shell, and it will create a static file server for the
Now you can visit http://localhost:5000 in the browser. If you get a 404 error for some static files, please wait a minute for the building to complete.
What happens after you run
Copy some necessary resources (
index.html, extensions config, libraries, etc.) to the
packages/vscode and run
yarn gulp compile-web to build the necessary extensions, then copy it to the
packages/vscode and run
yarn watch (the native watch of vscode), it will trigger a new build if something in it has been changed.
src directory, merge it in to
packages/vscode/src if something in it has been changed. (When a new file is merged into
packages/vscode/src, it will trigger the watcher that is described in Step 3)
extensions/githubsurf and run
yarn watch, it will trigger a new build if something has been changed.
extensions directory and the
packages/vscode/out directory, merge them into the
dist directory if something changed in them.
Note that since we have modified the source code of VS Code, it may get into trouble when merging a newer version VS Code.
It is a little laborious to complete the watch process, but I didn't think of a better solution.
Put simply, we build the necessary code and do a minify. The minify script is modified from Code Server.
extensions - custom VS Code extensions that don't come with VS Code natively.
src - the code in here will be patched into VS Code source.
scripts - some scripts for build, watch, package, etc.
resources - some resource files such as templates, pictures, configuration files, etc.