Skip to content

Commit 26fcdb7

Browse files
spekulatiusspekulatius
authored
doc: adding first draft of the documentation site (Kocal#588)
Hello @Kocal As discussed in Kocal#586, I've prepared a VuePress site in detail this contains: - It lives in `docs/` and has it's own `package.json`. - The development and production workflow from the wiki, - The Vue Devtools solution as a separate page - Rewording of a few sentences to make them work in the context and added a few more text blocks for it. - Turning code-blocks into the right format for VuePress - Turning Notes into VuePress note-blocks This is a first draft and it can be updated/tweaked as you like. I'm keen to see if goes in the right direction for you. Let me know what you think :) Thank you, Peter
1 parent ec8a66b commit 26fcdb7

File tree

10 files changed

+8134
-0
lines changed

10 files changed

+8134
-0
lines changed

‎docs/.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
node_modules/
2+
.vuepress/dist/
3+
yarn.lock

‎docs/.vuepress/config.js‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
module.exports = {
2+
title: 'Vue Web-Extension - a web-extension boilerplate for VueJS',
3+
description: '🛠️ A boilerplate for quickly starting a web extension with Vue, webpack 4, ESLint and more!',
4+
5+
plugins: {
6+
'sitemap': { hostname: 'https://vue-web-extension.netlify.app/', changefreq: 'monthly' },
7+
'seo': {},
8+
9+
'@vuepress/pwa': {
10+
serviceWorker: true,
11+
updatePopup: false
12+
}
13+
},
14+
serviceWorker: true,
15+
16+
themeConfig: {
17+
domain: 'https://vue-web-extension.netlify.app/',
18+
repo: 'Kocal/vue-web-extension',
19+
docsDir: 'docs',
20+
editLinks: true,
21+
lastConfig: 'Last updated',
22+
serviceWorker: {
23+
updatePopup: true,
24+
},
25+
smoothScroll: true,
26+
sidebar: [
27+
{
28+
title: 'Intro',
29+
collapsable: false,
30+
children: [
31+
'intro/setup',
32+
'intro/development-workflow',
33+
'intro/production-workflow',
34+
],
35+
},
36+
{
37+
title: 'Development',
38+
collapsable: false,
39+
children: [
40+
'development/Vue-Devtools',
41+
],
42+
},
43+
{
44+
title: 'Support',
45+
collapsable: false,
46+
children: [
47+
'support',
48+
],
49+
},
50+
]
51+
}
52+
};

‎docs/README.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
home: true
3+
heroText: Vue Web-Extension Boilerplate
4+
tagline: A boilerplate for quickly starting a web extension with Vue, webpack 4, ESLint and more!
5+
actionText: Get Started →
6+
actionLink: /intro/setup.html
7+
features:
8+
- title: Vue-Powered
9+
details: Enjoy the dev experience of Vue + webpack building your extension
10+
- title: Ready-To-Go
11+
details: The Vue-Web-Extension boilerplate gives you everything you need to get started quickly
12+
- title: Fast Development
13+
details: With Vuex, Vue Router, and Axois prepared you can start directly to developing
14+
footer: MIT Licensed | Copyright © 2018-present Hugo Alliaume
15+
---

‎docs/development/Vue-Devtools.md‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# Using Vue Devtools on your popup
2+
3+
By default, you can't use [Vue Devtools](https://github.com/vuejs/vue-devtools) on your popup page. The issue has been [discussed](https://github.com/vuejs/vue-devtools/issues/120).
4+
5+
[@wujunchuan](https://github.com/wujunchuan) found a solution to make it works anyway.
6+
7+
## Install and run Vue Devtools
8+
9+
Run `npm i -g @vue/devtools`, then run `vue-devtools`.
10+
11+
## Configuring your extension
12+
13+
A new window opens, copy the first `<script>` (it should be something like `<script src="http://localhost:8098"></script>`).
14+
15+
16+
### Updating your .html
17+
18+
Then update your `src/popup/popup.html` like this:
19+
20+
``` diff
21+
<!DOCTYPE html>
22+
<html lang="en">
23+
<head>
24+
<meta charset="UTF-8">
25+
<title>Title</title>
26+
<link rel="stylesheet" href="popup.css">
27+
+ <% if (NODE_ENV === 'development') { %>
28+
+ <!-- Load Vue Devtools remote ONLY in development -->
29+
+ <script src="http://localhost:8098"></script>
30+
+ <% } %>
31+
</head>
32+
...
33+
```
34+
35+
::: tip
36+
Since [#336](https://github.com/Kocal/vue-web-extension/pull/336), it is now possible to use [EJS](http://ejs.co/) on HTML files. Also it automatically inject all environment variables from `process.env`.
37+
:::
38+
39+
40+
### Updating Content Security Policy
41+
42+
You also need to update Content Security Policy of your extension. For this, update your `webpack.config.js` by adding `http://localhost:8098` in `manifest.json`'s `content_security_policy`:
43+
44+
``` diff
45+
{
46+
from: 'manifest.json',
47+
to: 'manifest.json',
48+
transform: (content) => {
49+
const jsonContent = JSON.parse(content);
50+
jsonContent.version = version;
51+
52+
if (config.mode === 'development') {
53+
- jsonContent['content_security_policy'] = "script-src 'self' 'unsafe-eval'; object-src 'self'";
54+
+ jsonContent['content_security_policy'] = "script-src 'self' 'unsafe-eval' http://localhost:8098; object-src 'self'";
55+
}
56+
57+
return JSON.stringify(jsonContent, null, 2);
58+
},
59+
```
60+
61+
::: tip
62+
1. You should restart webpack to apply modification.
63+
2. You should disable and re-enable your extension in Chrome, to take care of `manifest.json` changes.
64+
:::
65+
66+
67+
### Opening your popup
68+
69+
After that, you can open your popup and normally you will see a message like `Connected to Vue.js devtools`.
70+
71+
To make your development easier, you can open your popup in a new tab: `chrome-extension://<extension id>/popup/popup.html`.

‎docs/intro/development-workflow.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Development Workflow
2+
3+
Below you find the basic steps of the intended development workflow.
4+
5+
6+
## Watching mode and Hot Module Reload
7+
8+
Watching for modifications can be done using `npm run build:dev`.
9+
10+
It also enables [Hot Module Reloading](https://webpack.js.org/concepts/hot-module-replacement), using the [webpack-extension-reloader](https://github.com/rubenspgcavalcante/webpack-extension-reloader) plugin.
11+
12+
::: tip
13+
Keep in mind that HMR only works for your **background** entry.
14+
:::
15+
16+
17+
## Build a development version of the extension
18+
19+
Run `npm run build:dev` to build the extension into `dist` folder for **development**. This build isn't intended to be released. To get a release-ready zip-file see the instructions on the [production-workflow](/intro/production-workflow.html).

‎docs/intro/production-workflow.md‎

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
# Production workflow
2+
3+
The following steps describe the intended release process and optional services to use (e.g. Travis).
4+
5+
6+
## Handle extension version
7+
8+
If you take a look to your `src/manifest.json`, you will see that `version` is `null`.
9+
10+
When building, it injects the version of your `package.json` in your `src/manifest.json`. That means you should not update `manifest.json`'s directly.
11+
12+
By doing this, it means that you could use one of the following commands to easily update your version:
13+
14+
```bash
15+
npm version major # 1.x.x -> 2.x.x, when you release a breaking change
16+
npm version minor # x.1.x -> x.2.x, when you release a feature
17+
npm version patch # x.x.1 -> x.x.2, when you release a patch
18+
npm version 1.2.3 # custom version
19+
20+
# for yarn:
21+
yarn version --major
22+
yarn version --minor
23+
yarn version --patch
24+
yarn version --new-version 1.2.3
25+
```
26+
27+
::: tip Tips
28+
1. It is recommended to follow [Sementic Versioning](https://semver.org/) rules!
29+
2. Using `npm version` or `yarn version` will create update your `package.json`, create a new commit and a new tag, this is really helpful!
30+
:::
31+
32+
33+
## Building for production
34+
35+
Once you have updated your version, you can run:
36+
37+
```bash
38+
npm run build
39+
npm run build-zip
40+
41+
# for yarn:
42+
yarn build
43+
yarn build-zip
44+
```
45+
46+
Those commands will:
47+
48+
- build your extension for production (and use your `package.json` version for your `manifest.json`), located in `dist/`
49+
- build a `.zip`, located in `dist/zip/<your-extension-name>-<version>.zip`
50+
51+
When publishing on the [Chrome Web Store](https://chrome.google.com/webstore) (or [Firefox Add-ons](https://addons.mozilla.org)), you should upload your fresh `.zip`!
52+
53+
54+
## Automatic build and release with Travis
55+
56+
If you are using [Travis](https://travis-ci.com/), you can setup [GitHub Releases upload](https://docs.travis-ci.com/user/deployment/releases/) in order to automatically build a zip of your extension and attach it to your GitHub releases ([example](https://github.com/Kocal-Web-Extensions/Solary/releases/tag/v1.9.0)):
57+
58+
```yaml
59+
script:
60+
- yarn build
61+
- yarn build-zip
62+
63+
before_deploy:
64+
- export RELEASE_EXTENSION_FILE=$(ls dist-zip/*.zip)
65+
- echo "Deploying ${RELEASE_EXTENSION_FILE} to GitHub releases"
66+
67+
deploy:
68+
provider: releases
69+
api_key:
70+
secure: <YOUR API KEY>
71+
file: '${RELEASE_EXTENSION_FILE}'
72+
skip_cleanup: true # To keep, otherwise your `.zip` will be cleaned
73+
on:
74+
repo: <YOUR REPO>
75+
tags: true # Only on a new git tag
76+
```
77+
78+
This is really useful if you don't want to manually run commands from [Building for production](https://vue-web-extension.netlify.app/intro/production-workflow#building-for-production).

‎docs/intro/setup.md‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
# Getting started
2+
3+
Starting a new extension project using the boilerplate is done using [Vue CLI](https://cli.vuejs.org/). Installation steps for Vue CLI are provided on the website.
4+
5+
To initiate a new extension project run the following steps:
6+
7+
``` bash
8+
vue init kocal/vue-web-extension my-extension
9+
cd my-extension
10+
npm install
11+
npm run build
12+
```

‎docs/package.json‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"scripts": {
3+
"dev": "vuepress dev",
4+
"build": "vuepress build"
5+
},
6+
"dependencies": {
7+
"vuepress": "^1.4.1",
8+
"vuepress-plugin-seo": "^0.1.2",
9+
"vuepress-plugin-sitemap": "^2.3.1"
10+
}
11+
}

‎docs/support.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Support
2+
3+
Support and assistance in case of issues is done using the [GitHub Issues](https://github.com/Kocal/vue-web-extension/issues). Please search in the [open and closed issues](https://github.com/Kocal/vue-web-extension/issues?q=), if your question might have been answered previously. If you can't find an answer to your question, feel free to raise a new issue.
4+
5+
## Sponsor
6+
7+
If this boilerplate is useful for you or your business, you should consider [sponsoring the project](https://github.com/Kocal/vue-web-extension).

0 commit comments

Comments
 (0)