index.rst (5083B)
1 ====================== 2 Firefox Home (New Tab) 3 ====================== 4 5 All files related to Firefox Home, which includes content that appears on ``about:home`` and 6 ``about:newtab``, can be found in the ``browser/extensions/newtab`` directory. 7 Some of these source files (such as ``.js``, ``.jsx``, and ``.scss``) require an additional build step. 8 We are working on migrating this to work with ``mach``, but in the meantime, please 9 follow the following steps if you need to make changes in this directory: 10 11 For ``.sys.mjs`` files (system modules) 12 --------------------------------------------------- 13 14 No build step is necessary. Use ``mach`` and run mochitests according to your regular Firefox workflow. 15 16 For ``.js``, ``.jsx``, ``.scss``, or ``.css`` files 17 --------------------------------------------------- 18 19 Prerequisites 20 ````````````` 21 22 You will need the following: 23 24 - Node.js 10+ (On Mac, the best way to install Node.js is to use the install link on the `Node.js homepage`_) 25 - npm (packaged with Node.js) 26 27 To install node dependencies, run the following from the root of the mozilla-central repository. 28 (This command uses ``mach`` to call ``npm`` and ``node`` commands to ensure the correct versions of Node and npm are being referenced.) 29 30 .. code-block:: shell 31 32 ./mach newtab install 33 34 **IMPORTANT NOTE**: If you're using Windows, you may need to run the install command differently: 35 36 .. code-block:: shell 37 38 (cd browser/extensions/newtab && ../../../mach npm install) 39 40 Which files should you edit? 41 ```````````````````````````` 42 43 You should not make changes to ``.js`` or ``.css`` files in ``browser/extensions/newtab/css`` or 44 ``browser/extensions/newtab/data`` directory. Instead, you should edit the ``.jsx``, ``.js``, and ``.scss`` source files 45 in ``browser/extensions/newtab/content-src`` directory. These files will be compiled into the ``.js`` and ``.css`` files. 46 47 48 Building assets and running Firefox 49 ----------------------------------- 50 51 To build assets and run Firefox, run the following from the root of the mozilla-central repository: 52 53 .. code-block:: shell 54 55 ./mach newtab bundle && ./mach build && ./mach run 56 57 Continuous development / debugging 58 ---------------------------------- 59 60 For near real-time reloading, run the following commands in **two separate terminals** to automatically rebuild bundled files whenever JSX or SCSS files change. After making a change, `restart your local instance </devtools-user/browser_console/index.html#controlling-the-browser>`_ to apply the updates. Run the following terminal commands: 61 62 .. code-block:: shell 63 64 ./mach newtab watch 65 66 .. code-block:: shell 67 68 ./mach run 69 70 **IMPORTANT NOTE**: This task will add inline source maps to help with debugging, which changes the memory footprint. Do not use the ``watch`` task for profiling or performance testing! After finishing your work, **be sure to stop the watch process**. When stopped, it will automatically run a final bundle step to remove the temporary inline source maps. 71 72 73 Running tests 74 ------------- 75 The majority of New Tab / Messaging unit tests are written using 76 `mocha <https://mochajs.org>`_, and other errors that may show up there are 77 `SCSS <https://sass-lang.com/documentation/syntax>`_ issues flagged by 78 `stylelint <https://stylelint.io>`_. These things are all run using 79 ``npm test`` under the ``newtab`` slug in Treeherder/Try, so if that slug turns 80 red, these tests are what is failing. To execute them, do this: 81 82 .. code-block:: shell 83 84 ./mach npm test --prefix=browser/extensions/newtab 85 86 These tests are not currently run by ``mach test``, but there's a 87 `task filed to fix that <https://bugzilla.mozilla.org/show_bug.cgi?id=1581165>`_. 88 89 Windows isn't currently supported by ``npm test`` 90 (`path/invocation difference <https://bugzilla.mozilla.org/show_bug.cgi?id=1737419>`_). 91 To run newtab specific tests that aren't covered by ``mach lint`` and 92 ``mach test``: 93 94 .. code-block:: shell 95 96 ./mach npm run lint:stylelint --prefix=browser/extensions/newtab 97 ./mach npm run testmc:build --prefix=browser/extensions/newtab 98 ./mach npm run testmc:unit --prefix=browser/extensions/newtab 99 100 Mochitests and xpcshell tests run normally, using ``mach test``. 101 102 Code Coverage 103 ------------- 104 Our testing setup will run code coverage tools in addition to just the unit 105 tests. It will error out if the code coverage metrics don't meet certain thresholds. 106 107 If you see any missing test coverage, you can inspect the coverage report by 108 running 109 110 .. code-block:: shell 111 112 ./mach npm test --prefix=browser/extensions/newtab && 113 ./mach npm run debugcoverage --prefix=browser/extensions/newtab 114 115 Discovery Stream Developer tools 116 -------------------------------- 117 118 You can access the developer tools for the Discovery Stream components of about:newtab by 119 visiting `about:config` and setting `browser.newtabpage.activity-stream.asrouter.devtoolsEnabled` 120 to `true`. 121 122 Then, go to any `about:newtab` page and click on the wrench icon in the top-right corner. 123 124 Detailed Docs 125 ------------- 126 .. toctree:: 127 :titlesonly: 128 :glob: 129 130 v2-system-addon/* 131 132 .. _Node.js homepage: https://nodejs.org/