diff --git a/docs/en/docs/getting-started/_meta.json b/docs/en/docs/getting-started/_meta.json index 1e1cd48..4d15793 100644 --- a/docs/en/docs/getting-started/_meta.json +++ b/docs/en/docs/getting-started/_meta.json @@ -8,8 +8,8 @@ "label": "Create Your First Extension" }, { - "name": "remote-extension-execution", - "label": "Remote Extension Execution" + "name": "run-remote-extensions", + "label": "Run Remote Extensions" }, { "name": "templates", diff --git a/docs/en/docs/getting-started/create-your-first-extension.mdx b/docs/en/docs/getting-started/create-your-first-extension.mdx index f8e63d2..52220e5 100644 --- a/docs/en/docs/getting-started/create-your-first-extension.mdx +++ b/docs/en/docs/getting-started/create-your-first-extension.mdx @@ -8,13 +8,13 @@ Take a common task for some developers: searching on GitHub. **The problem:** I want to search on GitHub in the most convenient way. Imagine searching GitHub projects directly from your browser's URL bar. -The solution? Meet `github_search`, a tool that makes this possible. +The solution? Meet github_search, a tool that makes this possible. ![howiwant.png](../../../../assets/getting-started/howiwant.png) ## The Plan -Our goal is to make searching GitHub projects as easy as searching on Google. To avoid irrelevant searches when the user decides to search something else, let's reserve a keyword for our extension: if the user types "gh", followed by a tab click, will activate our extension to trigger our search. +Our goal is to make searching GitHub projects as easy as searching on Google. To avoid irrelevant searches when the user decides to search for something else, let's reserve a keyword for our extension: if the user types "gh," followed by a tab click, it will activate our extension to trigger the search. ![search.png](../../../../assets/getting-started/search.png) @@ -32,12 +32,11 @@ Let's use the Extension.js `create` command to bootstrap a minimal extension for }} /> -## Step 1 - Create the manifest file +## Step 2 - Create the manifest file
-> Step 1 Demo +> Step 2 Demo -Every extension starts with a manifest file. It tells the browser information about the extension's metadata, permissions, and files that the extension needs to run properly. Based on the [plan above](#plan), we want a custom search shortcut "gh" that will link us to GitHub search. We are also adding a service_worker script to handle user events logic. +Every extension starts with a manifest file. It tells the browser information about the extension's metadata, permissions, and files that the extension needs to run properly. Based on the [plan above](#plan), we want a custom search shortcut "gh" that will link us to GitHub search. We are also adding a service worker script to handle user events logic. -```jsx +```json { "manifest_version": 3, "name": "GitHub Search", "version": "1.0", - "omnibox": {"keyword" : "gh"}, + "omnibox": { "keyword": "gh" }, "background": { "service_worker": "service_worker.js" } } ``` -- `omnibox.keyword` when the keyword `gh` is set, an event will be fired. -- `background.service_worker` will listen to the event that we just fired. +- `omnibox.keyword`: When the keyword `gh` is set, an event will be fired. +- `background.service_worker`: Will listen to the event that we just fired. -## Step 2 - Create the Background Service Worker +## Step 3 - Create the Background Service Worker -In the context of a browser extension, the background service worker is where the extension can set listeners for all sorts of browser events. +In the context of a browser extension, the background service worker is where the extension can set listeners for various browser events. In our case, we need to add a script that listens to input events in the omnibox, so once the user types what they want to search, GitHub can return the correct data. Let's create a `service_worker.js` file for this purpose: ```js -// When the user has accepted what is typed into the omnibox. +When the user has accepted what is typed into the omnibox. chrome.omnibox.onInputEntered.addListener((text) => { - // Convert any special character (spaces, &, ?, etc) - // into a valid character for the URL format. + Convert any special character (spaces, &, ?, etc) + into a valid character for the URL format. const encodedSearchText = encodeURIComponent(text); const url = `https://github.com/search?q=${encodedSearchText}&type=issues`; @@ -90,13 +89,12 @@ chrome.omnibox.onInputEntered.addListener((text) => { The script above will open a new tab with GitHub search results whenever you enter something after "gh" in the URL bar. -## Step 3 - Load Your Extension +## Step 4 - Load Your Extension If you take a look at your `package.json` file now, it looks more or less like this: ```json { - // ...your extension metadata "scripts": { "dev": "extension@latest dev", "start": "extension start", @@ -110,16 +108,19 @@ If you take a look at your `package.json` file now, it looks more or less like t These scripts are the main scripts used by Extension.js for development mode. To preview your extension, let's run it for the first time. -``` -npm run dev -``` + If all goes well, you should see a screen like the following:
-## Use `Microsoft Edge` to Kickstart Any Sample +## Use Microsoft Edge to Kickstart Any Sample -`Extension` supports a variety of browsers, including Microsoft Edge. To start an Edge-compatible extension, simply: +Extension.js supports a variety of browsers, including Microsoft Edge. To start an Edge-compatible extension, follow these steps: 1. Open your terminal. -2. Navigate to your desired project directory. -3. Execute: - ```bash - npx extension@latest dev --browser=edge - ``` - Tailor your command by replacing `` with the specific sample you're interested in. +2. Navigate to the directory where you want to create your project. +3. Run this command: -> See the example below where we request the sample [magic8ball](https://github.com/GoogleChrome/chrome-extensions-samples/tree/main/api-samples/topSites/magic8ball) from from [Google Chrome Extension Samples](https://github.com/GoogleChrome/chrome-extensions-samples) using Edge as the runtime browser. + --browser=edge", + pnpm: "pnpx extension@latest dev --browser=edge", + yarn: "yarn dlx extension --browser=edge", + }} +/> + +Replace `` with the sample you want to use. + +> In the example below, we request the [magic8ball sample](https://github.com/GoogleChrome/chrome-extensions-samples/tree/main/api-samples/topSites/magic8ball) from [Google Chrome Extension Samples](https://github.com/GoogleChrome/chrome-extensions-samples) using Edge as the target browser.
-## Some Tips To Help You Get Started +## Tips to Get Started -- To use TypeScript, add a `tsconfig.json` file to the root of your extension. -- To use React, just ensure you have it as a dependency in your `package.json`. -- Any `tsconfig.json` with React support makes your project React/TypeScript ready. +- To use TypeScript, add a `tsconfig.json` file to the root of your project. +- To use React, add React as a dependency in your `package.json`. +- Any `tsconfig.json` with React support will make your project ready for React and TypeScript. - If you need to handle assets not declared in the manifest, learn more about [Special Folders](#). ## Next Steps -Start exploring the world of browser extension@latest development with `Extension` by [Create Your First Extension](#). +Start exploring browser extension development with Extension.js by [creating your first extension](#). diff --git a/docs/en/docs/getting-started/remote-extension-execution.mdx b/docs/en/docs/getting-started/run-remote-extensions.mdx similarity index 70% rename from docs/en/docs/getting-started/remote-extension-execution.mdx rename to docs/en/docs/getting-started/run-remote-extensions.mdx index b140aa0..ad0169e 100644 --- a/docs/en/docs/getting-started/remote-extension-execution.mdx +++ b/docs/en/docs/getting-started/run-remote-extensions.mdx @@ -1,25 +1,20 @@ -# Remote Extension Execution +import { PackageManagerTabs } from "@theme"; -One of the coolest features of Extension is the ability to execute remote extensions. By running a valid GitHub URL as the command argument, `Extension` downloads and execute the extension files against the target browser, as if you would using any local extension. +# Run Remote Extensions Directly from GitHub -This is useful during prototype steps where you want to create something based on a working extension sample, such as [Chrome Samples](#) or [MDN samples](#). +One of the coolest features of Extension.js is the ability to execute remote extensions. By running a valid GitHub URL as the command argument, Extension.js downloads and executes the extension files against the target browser, as if you were using any local extension. -``` - -``` +This is useful during the prototyping stage when you want to create something based on a working extension sample, such as [Chrome Samples](#) or [MDN samples](#). ## Remote `dev` command -The `dev` command runs the extension in development mode with support for reloading upon file changes. By passing a valid GitHub URL (as long as there is a valid manifest file), Extension will download the files to your current directory and run your extension against the current browser. +The `dev` command runs the extension in development mode with support for reloading upon file changes. By passing a valid GitHub URL (as long as there is a valid manifest file), Extension.js will download the files to your current directory and run your extension against the current browser. In the example below, we are using the remote Chrome Sample [page_redder](https://github.com/GoogleChrome/chrome-extensions-samples/tree/main/functional-samples/sample.page-redder) from [Google Chrome Extension Samples](https://github.com/GoogleChrome/chrome-extensions-samples).
-`Extension` has a default `create` command that allows you to generate the foundations of your next extension project (see demo above). It also supports templates via `--template` flag. +The `extension` package has a default `create` command that generates the foundation of your next extension project (as shown in the demo above). You can also use the `--template` flag to specify a template. -For a list of all supported templates, see [Templates](/docs/getting-started/templates). +For a list of all supported templates, check out the [Templates](/docs/getting-started/templates) page. -## Usage With An Existing Extension +## Use with an Existing Extension
-If you have an existing extension which is using a package manager, you can install the `extension` package and manually create the scripts used to run your extension. See the demo above or follow these instructions to get it done: +If you already have an extension and are using a package manager, you can install the `extension` package and manually create the scripts needed to run your extension. Refer to the demo above or follow these steps: -**Step 1 - Install Extension as a `devDependency`** +### Step 1 - Install Extension.js as a `devDependency` -```sh -npm install extension --save-dev -``` + -**Step 2 - Link your npm scripts with the executable `Extension` commands** +### Step 2 - Link your npm scripts to the `extension` commands ```json { @@ -77,21 +83,20 @@ npm install extension --save-dev "start": "extension start" }, "devDependencies": { - // ...other deps, "extension": "latest" } } ``` -Done. You are all set! +That's it! You're all set. -- To develop the extension, run `npm run dev`. -- To visualize the extension in production mode, run `npm run start`. -- To build the extension in production mode, run `npm run build`. +- Run `npm run dev` to develop your extension. +- Run `npm run start` to preview your extension in production mode. +- Run `npm run build` to bundle your extension for production. ## Next Steps - Learn how to [Create Your First Extension](/docs/getting-started/create-your-first-extension). -- Have an idea in mind? Check the built-in [Templates](/docs/getting-started/templates) available. +- Have an idea? Explore the built-in [Templates](/docs/getting-started/templates). --- diff --git a/rspress.config.ts b/rspress.config.ts index 3f623dc..c44c937 100644 --- a/rspress.config.ts +++ b/rspress.config.ts @@ -88,8 +88,7 @@ export default defineConfig({ "Create cross-browser extensions with no build configuration", label: "English", editLink: { - docRepoBaseUrl: - "https://github.com/extension-js/docs/tree/main/docs", + docRepoBaseUrl: "https://github.com/extension-js/docs/tree/main/docs", text: "đź“ť Edit this page on GitHub", }, searchPlaceholderText: "Search Documentation",