diff --git a/developer_manual/digging_deeper/npm.rst b/developer_manual/digging_deeper/npm.rst index 949676a53a3..df5aae4b65b 100644 --- a/developer_manual/digging_deeper/npm.rst +++ b/developer_manual/digging_deeper/npm.rst @@ -85,14 +85,17 @@ npm run lint (optional) ----------------------- Nextcloud apps that use linting tools for consistent code formatting typically add a ``lint`` script to their -``package.json`` and install the appropriate `eslint config `_: +``package.json`` and install the appropriate `eslint config `_ +(see the ESLint section in :doc:`../getting_started/coding_standards/javascript` for a copyable ``eslint.config.js``). + +With the flat config format, file extensions are declared in ``eslint.config.js``, so pass directories instead of ``--ext``: .. code-block:: json { "scripts": { - "lint": "eslint --ext .js,.vue src", - "lint:fix": "eslint --ext .js,.vue src --fix" + "lint": "eslint src", + "lint:fix": "eslint src --fix" } } diff --git a/developer_manual/getting_started/coding_standards/javascript.rst b/developer_manual/getting_started/coding_standards/javascript.rst index 6e54416e030..8a7059d99e5 100644 --- a/developer_manual/getting_started/coding_standards/javascript.rst +++ b/developer_manual/getting_started/coding_standards/javascript.rst @@ -11,7 +11,7 @@ General rules and advice - Nextcloud uses Vue.js for its interface, for a consistent user interface we recommend apps to also use Vue with :ref:`provided components `. Yet also vanilla JavaScript and HTML can be used. - We recommend using Typescript for its type checking and improved static code analysis features. -- Do not create global variables, instead if needed use global namespace objects like ``OCA.YourApp.…`` +- Do not create global variables, instead if needed use global namespace objects like ``OCA.YourApp.…`` - Use JavaScript strict mode (automatically the case when using JavaScript modules) ESLint config @@ -19,7 +19,26 @@ ESLint config There is a shared configuration for `eslint `_ that you can use to automatically format your Nextcloud apps's JavaScript and Typescript code. It consists of two parts: a `config package `_ that contains the formatting preferences -and a `plugin `_ to detect deprecated and removed APIs in your code. See their readmes for instructions. +and a `plugin `_ to detect deprecated and removed APIs in your code. + +Install the shared config (it pulls in ESLint and the Nextcloud plugin): + +.. code-block:: bash + + npm install --save-dev @nextcloud/eslint-config + +Add an ``eslint.config.js`` in your app root using the flat config format (required since ``@nextcloud/eslint-config`` v9 / ESLint 9+): + +.. code-block:: javascript + + import { recommended } from '@nextcloud/eslint-config' + + export default [ + ...recommended, + ] + +``recommended`` covers TypeScript and Vue 3. Alternatives such as ``recommendedJavascript`` and ``recommendedVue2`` are documented in the `config package README `_. +See also :ref:`app-npm` for the ``lint`` / ``lint:fix`` npm scripts. Filesystem structure ^^^^^^^^^^^^^^^^^^^^ @@ -79,7 +98,7 @@ Naming and casing - For readability only capitalize the first letter of abbreviations like ``callHttpApi()`` instead of ``callHTTPAPI()``. - Sub-components should be prefixed. - E.g. splitting a component like ``FileListEntry`` into smaller components called ``FileListEntryName``, ``FileListEntryIcon`` … + E.g. splitting a component like ``FileListEntry`` into smaller components called ``FileListEntryName``, ``FileListEntryIcon`` … - Components should not have single-word names, this could conflict with current or future native HTML tags as these are always single-word. E.g. if you have a settings view, do not call it ``Settings`` but ``SettingsView`` or ``UserSettings`` etc. @@ -87,8 +106,8 @@ Naming and casing :widths: 50 50 :header-rows: 1 - * - ✅ Do - - ❌ Don't + * - ✅ Do + - ❌ Don't * - .. code-block:: javascript @@ -111,8 +130,8 @@ Naming and casing :widths: 50 50 :header-rows: 1 - * - ✅ Do - - ❌ Don't + * - ✅ Do + - ❌ Don't * - .. code-block:: javascript @@ -141,8 +160,8 @@ Semicolons :widths: 50 50 :header-rows: 1 - * - ✅ Do - - ❌ Don't + * - ✅ Do + - ❌ Don't * - .. code-block:: javascript @@ -170,8 +189,8 @@ Strings :widths: 50 50 :header-rows: 1 - * - ✅ Do - - ❌ Don't + * - ✅ Do + - ❌ Don't * - .. code-block:: javascript @@ -186,8 +205,8 @@ Strings :widths: 50 50 :header-rows: 1 - * - ✅ Do - - ❌ Don't + * - ✅ Do + - ❌ Don't * - .. code-block:: javascript @@ -205,8 +224,8 @@ Arrays :widths: 50 50 :header-rows: 1 - * - ✅ Do - - ❌ Don't + * - ✅ Do + - ❌ Don't * - .. code-block:: javascript @@ -225,8 +244,8 @@ Arrays :widths: 50 50 :header-rows: 1 - * - ✅ Do - - ❌ Don't + * - ✅ Do + - ❌ Don't * - .. code-block:: javascript @@ -280,8 +299,8 @@ Functions :widths: 50 50 :header-rows: 1 - * - ✅ Do - - ❌ Don't + * - ✅ Do + - ❌ Don't * - .. code-block:: javascript @@ -296,8 +315,8 @@ Functions :widths: 50 50 :header-rows: 1 - * - ✅ Do - - ❌ Don't + * - ✅ Do + - ❌ Don't * - .. code-block:: javascript @@ -351,8 +370,8 @@ Functions :widths: 50 50 :header-rows: 1 - * - ✅ Do - - ❌ Don't + * - ✅ Do + - ❌ Don't * - .. code-block:: javascript @@ -390,8 +409,8 @@ Functions :widths: 50 50 :header-rows: 1 - * - ✅ Do - - ❌ Don't + * - ✅ Do + - ❌ Don't * - .. code-block:: javascript @@ -433,8 +452,8 @@ Functions :widths: 50 50 :header-rows: 1 - * - ✅ Do - - ❌ Don't + * - ✅ Do + - ❌ Don't * - .. code-block:: javascript @@ -456,8 +475,8 @@ Functions :widths: 50 50 :header-rows: 1 - * - ✅ Do - - ❌ Don't + * - ✅ Do + - ❌ Don't * - .. code-block:: javascript @@ -492,8 +511,8 @@ Objects :widths: 50 50 :header-rows: 1 - * - ✅ Do - - ❌ Don't + * - ✅ Do + - ❌ Don't * - .. code-block:: javascript @@ -514,8 +533,8 @@ Objects :widths: 50 50 :header-rows: 1 - * - ✅ Do - - ❌ Don't + * - ✅ Do + - ❌ Don't * - .. code-block:: javascript @@ -540,8 +559,8 @@ Objects :widths: 50 50 :header-rows: 1 - * - ✅ Do - - ❌ Don't + * - ✅ Do + - ❌ Don't * - .. code-block:: javascript @@ -559,8 +578,8 @@ Objects :widths: 50 50 :header-rows: 1 - * - ✅ Do - - ❌ Don't + * - ✅ Do + - ❌ Don't * - .. code-block:: javascript @@ -575,8 +594,8 @@ Objects :widths: 50 50 :header-rows: 1 - * - ✅ Do - - ❌ Don't + * - ✅ Do + - ❌ Don't * - .. code-block:: javascript @@ -638,8 +657,8 @@ Here's why: :widths: 50 50 :header-rows: 1 - * - ✅ Do - - ❌ Don't + * - ✅ Do + - ❌ Don't * - .. code-block:: javascript @@ -666,8 +685,8 @@ Control structures :widths: 50 50 :header-rows: 1 - * - ✅ Do - - ❌ Don't + * - ✅ Do + - ❌ Don't * - .. code-block:: javascript @@ -696,8 +715,8 @@ Control structures :widths: 50 50 :header-rows: 1 - * - ✅ Do - - ❌ Don't + * - ✅ Do + - ❌ Don't * - .. code-block:: javascript diff --git a/developer_manual/getting_started/coding_standards/php.rst b/developer_manual/getting_started/coding_standards/php.rst index bd768a77a2b..813f014b313 100644 --- a/developer_manual/getting_started/coding_standards/php.rst +++ b/developer_manual/getting_started/coding_standards/php.rst @@ -4,6 +4,52 @@ PHP coding standards Starting with Nextcloud 19 there is a shared `PHP Coding Standards Fixer `_ configuration you can use to automatically format your app's source code. For full details see the `repository on GitHub `_. +Setup +----- + +Install the shared configuration as a development dependency: + +.. code-block:: bash + + composer require --dev nextcloud/coding-standard + +Create a ``.php-cs-fixer.dist.php`` in your app root: + +.. code-block:: php + + getFinder() + ->ignoreVCSIgnored(true) + ->notPath('build') + ->notPath('l10n') + ->notPath('src') + ->notPath('vendor') + ->in(__DIR__); + return $config; + +Add convenience scripts to ``composer.json``: + +.. code-block:: json + + { + "scripts": { + "cs:check": "php-cs-fixer fix --dry-run --diff", + "cs:fix": "php-cs-fixer fix" + } + } + +Then run ``composer cs:check`` to list violations, or ``composer cs:fix`` to apply fixes. +Exclude ``.php-cs-fixer.dist.php`` and ``.php-cs-fixer.cache`` from your release build. + Always use::