Skip to content

Latest commit

 

History

History
86 lines (45 loc) · 5.65 KB

guide.md

File metadata and controls

86 lines (45 loc) · 5.65 KB

How it works

GitHub1s is based on VS Code 1.66.2 now. VS Code can be built for a browser version officially. I also used the code and got inspired by Code Server.

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 GitHub1s is to implement a VS Code Extension (includes FileSystemProvider) using GitHub REST API.

We may switch to the GitHub GraphQL API for more friendly user experience in the future, thanks to @xcv58 and @kanhegaonkarsaurabh. See details at Issue 12.

GitHub1s 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 GitHub1s could be reliable (GitHub is very reliable) because nobody needs to pay the web hosting bills.

We deploy GitHub1s on Cloudflare Pages now for minimize delays in loading and better developer experience. Thanks for the wonderful service provide by Cloudflare.

Rate Limit

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 GitHub1s, 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.

Sourcegraph API

Due to the potential RateLimit of the GitHub API, we will prioritize the use of the Sourcegraph API for public repositories, with the exception of the Read interface, the code search capability is also provided by the Sourcegraph API.

By default, GitHub1s will only try to use the GitHub API when the Sourcegraph API request fails, and you can adjust this option in the settings.

Development

As you see, running GitHub1s locally is not difficult. After cloning the repository, just run these commands:

$ npm install
$ npm run watch

Then, there will be a new directory named dist generated in the project root. The npm run watch:dev-server (part of npm run watch command) will automatically open http://localhost:8080 in the browser.

If you get a 404 error for some static files, please wait a minute for the building to complete.

Watch Mode

What happens after you run npm run watch-with-vscode?

  1. Copy some necessary resources (index.html, favicons.ico, etc.) to the dist directory.

  2. This command will compile the codes in src and generate application entry script (see webpack.config.js). This command also compile the custom extensions (for example github1s) in extensions directory.

  3. Redirect vscode-web static requests (vscode, extensisions, dependencies) to vscode-web/lib/vscode which should be generated by vscode compile process.

You should also compile the vscode manually in another terminal.

  1. Go to vscode-web and run npm install && npm run watch (the native watch of vscode), it will trigger a new build if something in it has been changed.

  2. This command will alose watch the vscode-web/src and vscode-web/extensions directory, merge it in to vscode-web/lib/vscode if something in it has been changed. (When a new file is merged into lib/vscode, it will trigger the watcher that is described in Step 3)

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.

What happens after you run npm run watch?

It's the same procedure as `` without the step 3. Instead of the local VS Code, it uses the prebuilt @github1s/vscode-web version.

Build mode

Put simply, we build the necessary code and do a minify. The minify script is modified from Code Server.

Directory Structure

  • 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.

  • vscode-web - This contains the code to patch VS Code.

  • scripts - some scripts for build, watch, package, etc.

  • resources - some resource files such as templates, pictures, configuration files, etc.