Before you start developing in Subscribe with Google, check out these resources:
- CONTRIBUTING.md has details on various ways you can contribute to the Subscribe with Google.
- If you're developing in Subscribe with Google, you should read the Contributing code.
Now that you have all of the files copied locally you can actually build the code and run a local server to try things out. We use Node.js, Closure Compiler, and the Gulp build system to build swg-js
and start up a local server that lets you try out your changes.
-
Install the latest LTS version of Node.js (which includes npm). If you're on Mac or Linux, an easy way to install Node.js is with
nvm
: here.nvm install --lts
-
If you have a global install of Gulp, uninstall it. (Instructions here. See this article for why.)
npm uninstall -g gulp
-
Install Swgjs with the following bash commands, instead of simply cloning the repo. These commands install Swgjs in a standardized location and they also install helpful bash scripts, like
swgjs_start_server
.curl https://raw.githubusercontent.com/subscriptions-project/swg-js/main/shortcuts.sh -o /tmp/swgjs-shortcuts.sh source /tmp/swgjs-shortcuts.sh swgjs_install && swgjs_add_shortcuts_to_bashrc
-
In your local repository directory (e.g.
~/projects/swgjs
), install the packages that SWG uses by runningnpm i
You should see a progress indicator and some messages scrolling by.
Now whenever you're ready to build swg-js
and start up your local server, simply go to your local repository directory and run:
npx gulp
Running the npx gulp
command will compile the code and start up a Node.js server listening on port 8000. Once you see a message like Finished 'default'
you can access the local server in your browser at http://localhost:8000
You can browse the http://localhost:8000/examples directory to see some demo pages for various SwG components and combination of components.
SwG uses Eslint to ensure code quality and Prettier to standardize code style. For easy development, here are two recommendations:
- Use a code editor with Eslint support to make sure that your code satisfies all of SwG's quality and style rules. Here is a list of editors with Eslint extension support.
- Set your editor to automatically fix Eslint errors in your code on save.
For example, if you use Visual Studio Code, you can install its Eslint plugin, and enable the eslint.autoFixOnSave
setting.
Alternatively, you can manually fix lint errors in your code by running:
npx gulp lint --local_changes --fix
For some local testing we refer to fake local URLs in order to simulate referencing third party URLs. This requires extra setup so your browser will know that these URLs actually point to your local server.
You can do this by adding this line to your hosts file (/etc/hosts
on Mac or Linux, %SystemRoot%\System32\drivers\etc\hosts
on Windows):
127.0.0.1 pub.localhost sp.localhost
Use the following Gulp commands:
Command | Description |
---|---|
npx gulp [1] |
Runs "watch" and "serve". Use this for standard local dev. |
npx gulp dist [1] |
Builds production binaries. |
npx gulp lint |
Validates against Google Closure Linter. |
npx gulp lint --watch |
Watches for changes in files, Validates against Google Closure Linter. |
npx gulp lint --fix |
Fixes simple lint warnings/errors automatically. |
npx gulp build [1] |
Builds the library. |
npx gulp check-links --files foo.md,bar.md |
Reports dead links in .md files. |
npx gulp clean |
Removes build output. |
npx gulp watch [1] |
Watches for changes in files, re-build. |
npx gulp unit |
Runs unit tests in Chrome. |
npx gulp unit --coverage |
Runs unit tests in code coverage mode. After running, the report will be available at test/coverage/index.html |
npx gulp e2e |
Runs end-to-end tests in Chrome. |
npx gulp serve |
Serves Scenic site on http://localhost:8000/. |
npx gulp serve --quiet |
Same as serve , with logging silenced. |
[1] On Windows, this command must be run as administrator.
For manual testing build Subscribe with Google and start the Node.js server by running npx gulp
.
assets/ - static assets and i18n translations build/ - (generated) intermediate generated files build-system/ - build infrastructure and development server contributing/ - docs for code contributors dist/ - (generated) Web releases are compiled here, then deployed to a CDN docs/ - documentation for publishers examples/ - example publisher website, used for local development src/ - source code and unit tests test/ - e2e tests and libraries for unit tests third_party/ - third party code, not developed by the Swgjs team