Skip to content

Commit

Permalink
Update Getting Started
Browse files Browse the repository at this point in the history
  • Loading branch information
@cezaraugusto
cezaraugusto committed Sep 11, 2024
1 parent 819db08 commit 745841a
Show file tree
Hide file tree
Showing 7 changed files with 138 additions and 132 deletions.
4 changes: 2 additions & 2 deletions docs/en/docs/getting-started/_meta.json
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
71 changes: 36 additions & 35 deletions docs/en/docs/getting-started/create-your-first-extension.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand All @@ -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

<div style={{ position: "relative", paddingBottom: "62.5%", height: 0 }}>
<iframe
src="https://www.loom.com/embed/1193dc69f7b74a56a5f5d9e0324c255d?sid=99132929-4c05-40e7-b804-3f242daf95ea"
frameBorder="0"
allowFullScreen
style={{
position: "absolute",
Expand All @@ -49,38 +48,38 @@ Let's use the Extension.js `create` command to bootstrap a minimal extension for
></iframe>
</div>

> 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`;

Expand All @@ -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",
Expand All @@ -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
```
<PackageManagerTabs
command={{
npm: "npm run dev",
pnpm: "pnpm run dev",
yarn: "yarn run dev",
}}
/>
If all goes well, you should see a screen like the following:
<div style={{ position: "relative", paddingBottom: "62.5%", height: 0 }}>
<iframe
src="https://www.loom.com/embed/777544977a32444ba6de4ff23bdaccbc?sid=360eb1b1-af3a-480b-9e71-41a7fb01ca6e"
frameBorder="0"
allowFullScreen
style={{
position: "absolute",
Expand All @@ -133,18 +134,18 @@ If all goes well, you should see a screen like the following:
That's it! You created your first browser extension that searches on GitHub!
## Step 4 - Making It Better
## Step 5 - Making It Better
To make our search results even better, let's add search suggestions directly in the URL bar by listening to input changes in the omnibox.
To improve our search results, let's add search suggestions directly in the URL bar by listening to input changes in the omnibox.
Update the `service_worker.js` file to start fetching suggestions from GitHub and display them as you type.
Update the `service_worker.js` file to fetch suggestions from GitHub and display them as you type.
```js
// service_worker.js
service_worker.js

// Create a debounce function to avoid excessive
// calls to the GitHub API while the user is still
// typing the search query.
Create a debounce function to avoid excessive
calls to the GitHub API while the user is still
typing the search query.
function debounce(fn, delay) {
let timeoutID;
return function (...args) {
Expand All @@ -153,7 +154,7 @@ function debounce(fn, delay) {
};
}

// When the user has changed what is typed into the omnibox.
When the user has changed what is typed into the omnibox.
chrome.omnibox.onInputChanged.addListener(
debounce(async (text, suggest) => {
const response = await fetch(
Expand All @@ -169,18 +170,18 @@ chrome.omnibox.onInputChanged.addListener(
}, 250),
);

// 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`;

chrome.tabs.create({ url });
});
```
Adding this code will let you see live search suggestions from GitHub right in your URL bar, making the search experience almost instant. Here is how it looks like when I type "undefined is not a function":
Adding this code will let you see live search suggestions from GitHub right in your URL bar, making the search experience even smoother.
![Updated result](./../../../../assets/getting-started/updated-result.png)
Expand All @@ -192,5 +193,5 @@ Congratulations! You've built a GitHub search extension. Experiment with it, imp
## Next Steps
- Learn how to load locally remotely hosted extensions in [Remote Extension Execution](../getting-started/remote-extension-execution).
- Create an extension using one of `Extension` [Templates](../getting-started/templates).
- Learn how to load remotely hosted extensions in [Remote Extension Execution](../getting-started/remote-extension-execution).
- Create an extension using one of Extension.js [Templates](../getting-started/templates).
69 changes: 39 additions & 30 deletions docs/en/docs/getting-started/get-started-immediately.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,15 +2,15 @@ import { PackageManagerTabs } from "@theme";

# 🔥 Get Started Immediately

Welcome to the fast track of browser extension@latest development with `Extension`! Whether you're looking to prototype quickly or delve into full-scale development, you've made the right choice. Let's get your development environment set up and running in no time.
Welcome to the fast track for developing cross-browser extensions with Extension.js. Whether you’re quickly prototyping or working on full-scale development, this guide will help you get started right away.

## Kickstart Any Sample from Chrome Extension Samples

Dive right into development by starting with a sample from the Chrome Extension Samples repository. It's a great way to get acquainted with best practices and save time:
Start development by using a sample from the Chrome Extension Samples repository. It's a great way to learn best practices and save time.

1. Open your terminal.
2. Navigate to the directory where you want your project.
3. Run the command:
2. Navigate to the directory where you want to create your project.
3. Run the following command:

<PackageManagerTabs
command={{
Expand All @@ -20,14 +20,13 @@ Dive right into development by starting with a sample from the Chrome Extension
}}
/>

**Note:** Replace `<sample-name>` with the name of the sample you wish to use from [Chrome Extension Samples](https://github.com/GoogleChrome/chrome-extensions-samples).
**Note:** Replace `<sample-name>` with the sample you want to use from [Chrome Extension Samples](https://github.com/GoogleChrome/chrome-extensions-samples).

See the example below where we request the 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).
See the example below, where we request the [page-redder sample](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).

<div style={{ position: "relative", paddingBottom: "62.5%", height: 0 }}>
<iframe
src="https://www.loom.com/embed/34fc48f3f7954bfa990e767c6a7172f0?sid=346f6a11-58d6-48a4-8935-aac8119d765d"
frameBorder="0"
allowFullScreen
style={{
position: "absolute",
Expand All @@ -39,24 +38,29 @@ See the example below where we request the sample [page-redder](https://github.c
></iframe>
</div>

## 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 <sample-name> --browser=edge
```
Tailor your command by replacing `<sample-name>` 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.
<PackageManagerTabs
command={{
npm: "npx extension@latest dev <sample-name> --browser=edge",
pnpm: "pnpx extension@latest dev <sample-name> --browser=edge",
yarn: "yarn dlx extension <sample-name> --browser=edge",
}}
/>

Replace `<sample-name>` 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.
<div style={{ position: "relative", paddingBottom: "62.5%", height: 0 }}>
<iframe
src="https://www.loom.com/embed/284d706379a84adabfdde6bd341b8d24?sid=24a4a6d5-5b30-4920-8a47-004540183aed"
frameBorder="0"
allowFullScreen
style={{
position: "absolute",
Expand All @@ -70,21 +74,26 @@ See the example below where we request the sample [page-redder](https://github.c

## Run Mozilla Add-Ons Using Edge

Bridge the gap between Firefox and Edge by running Mozilla Add-Ons using Edge:
You can also adapt Mozilla Add-Ons to run on Edge:

1. Navigate to your project directory.
2. Use the command:
```bash
npx extension@latest dev <addon-name> --browser=edge --polyfill=true
```
This will fetch a Mozilla Add-On and adapt it for Edge.
2. Run this command:

<PackageManagerTabs
command={{
npm: "npx extension@latest dev <addon-name> --browser=edge --polyfill=true",
pnpm: "pnpx extension@latest dev <addon-name> --browser=edge --polyfill=true",
yarn: "yarn dlx extension <addon-name> --browser=edge --polyfill=true",
}}
/>

This will fetch a Mozilla Add-On and adapt it for Edge.

> See the example below where we request the sample [Apply CSS](https://github.com/mdn/webextensions-examples/tree/main/apply-css) from [MDN WebExtensions Examples](https://github.com/mdn/webextensions-examples) using Edge as the runtime browser.
> Below is an example of fetching the [Apply CSS sample](https://github.com/mdn/webextensions-examples/tree/main/apply-css) from [MDN WebExtensions Examples](https://github.com/mdn/webextensions-examples) and running it on Edge.
<div style={{ position: "relative", paddingBottom: "62.5%", height: 0 }}>
<iframe
src="https://www.loom.com/embed/6eb724aad822413fb4fe9f52afec5576?sid=e2aa47a4-71d4-4ff1-887a-dcf8031ea917"
frameBorder="0"
allowFullScreen
style={{
position: "absolute",
Expand All @@ -96,13 +105,13 @@ Bridge the gap between Firefox and Edge by running Mozilla Add-Ons using Edge:
></iframe>
</div>

## 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](#).
Loading

0 comments on commit 745841a

Please sign in to comment.