prettier-plugin-solidity


> ℹ️ This README is for the new major version of Prettier Plugin Solidity.
>
> The differences from v1 are minimal, but there are some breaking changes.
>
> To migrate from v1, follow the migration guide.
>
> If you're looking for the previous version, check out the v1 branch.

A Prettier plugin for automatically formatting your Solidity code.

Installation and usage

$3

Install both prettier and prettier-plugin-solidity:

``Bash
npm install --save-dev prettier prettier-plugin-solidity
`

Run prettier on your contracts:

`Bash
npx prettier --write --plugin=prettier-plugin-solidity 'contracts/*/.sol'
`

You can add an npm script to run prettier on all your contracts:

`
"prettier": "prettier --write --plugin=prettier-plugin-solidity 'contracts/*/.sol'"
`

Or you can use it as part of your linting to check that all your code is prettified:

`
"lint": "prettier --list-different --plugin=prettier-plugin-solidity 'contracts/*/.sol'"
`

> Prettier Solidity only works with valid code. If there is a syntax error, nothing will be done and a parser error will be thrown.

$3

To use this package in the browser, you need to load Prettier's standalone bundle before loading the build provided in this package.

Prettier's unpkg field points to https://unpkg.com/prettier/standalone.js, in a similar way this plugin points to https://unpkg.com/prettier-plugin-solidity/dist/standalone.js.

Once the scripts are loaded you will have access to the globals prettier and prettierPlugins.

We follow Prettier's strategy for populating their plugins in the object prettierPlugins, you can load other plugins like https://unpkg.com/prettier@2.8.0/parser-markdown.js and Prettier will have access to multiple parsers.

`html

`

For more details, have a look at Prettier's documentation.

$3

If you are creating your own package to be run in a browser, you might want to import the standalone files directly.

`Javascript
import prettier from "prettier/standalone";
import solidityPlugin from "prettier-plugin-solidity/standalone";

async function format(code) {
return await prettier.format(code, {
parser: "slang",
plugins: [solidityPlugin],
});
}

const originalCode = "contract Foo {}";
const formattedCode = format(originalCode);
`

Configuration File

Prettier provides a flexible system to configure the formatting rules of a project. For more information please refer to the documentation.
The following is the default configuration internally used by this plugin.

`JSON
{
"plugins": ["prettier-plugin-solidity"],
"overrides": [
{
"files": "*.sol",
"options": {
"parser": "slang",
"printWidth": 80,
"tabWidth": 4,
"useTabs": false,
"singleQuote": false,
"bracketSpacing": false,
}
}
]
}
`

Note the use of the overrides property which allows for multiple configurations in case there are other languages in the project (i.e. JavaScript, JSON, Markdown).

Since Prettier v3.0.0, the plugin search feature has been removed so we encourage adding our plugin to the configuration file.

Most options are described in Prettier's documentation.

$3

Many versions of the Solidity compiler have changes that affect how the code should be formatted. This plugin, by default, tries to format the code in the most compatible way that is possible, but you can use the compiler option to nudge it in the right direction.

One example of this is import directives. Before 0.7.4, the compiler didn't accept multi-line import statements, so we always format them in a single line. But if you use the compiler option to indicate that you are using a version greater or equal than 0.7.4, the plugin will use multi-line imports when it makes sense.

The Solidity versions taken into consideration during formatting are:

- v0.7.4: Versions prior 0.7.4 had a bug that would not interpret correctly imports unless they are formatted in a single line.

`Solidity
// Input
import { Foo as Bar, Baz as Qux } from "/an/extremely/long/location";

// "compiler": undefined, parser: "antlr"
import { Foo as Bar, Baz as Qux } from "/an/extremely/long/location";

// "compiler": "0.7.3" (or lesser)
import { Foo as Bar, Baz as Qux } from "/an/extremely/long/location";

// "compiler": "0.7.4" (or greater)
import {
Foo as Bar,
Baz as Qux
} from "/an/extremely/long/location";
`

- v0.8.0: Introduced these changes
- The type byte has been removed. It was an alias of bytes1.
- Exponentiation is right associative, i.e., the expression abc is parsed as a(bc). Before 0.8.0, it was parsed as (ab)c.

`Solidity
// Input
bytes1 public a;
byte public b;

uint public c = 1 2 3;

// "compiler": undefined
bytes1 public a;
byte public b;

uint public c = 123;

// "compiler": "0.7.6" (or lesser)
bytes1 public a;
byte public b;

uint public c = (12)3;

// "compiler": "0.8.0" (or greater)
bytes1 public a;
bytes1 public b;

uint public c = 1(23);
`

You might have a multi-version project, where different files are compiled with different compilers. If that's the case, you can use overrides to have a more granular configuration:

`JSON
{
"overrides": [
{
"files": "contracts/v1/*/.sol",
"options": {
"compiler": "0.6.3"
}
},
{
"files": "contracts/v2/*/.sol",
"options": {
"compiler": "0.8.4"
}
}
]
}
`

| Default | CLI Override | API Override |
| --------------------------------------------------------------------------------------------- | --------------------- | ---------------------- |
| Inferred from pragma statements when using parser slang
None when using parser antlr | --compiler | compiler: "" |

$3

You can configure the parser used by Prettier Solidity. Two Solidity parsers are supported:

- Slang (the default), a more powerful and correct parser that results in better formatting for some edge cases, especially when comments are involved.
- Solidity Parser for JavaScript, an ANTLR-based parser. This is the version that Prettier Solidity v1 used by default. This parser is still supported in v2, but it's deprecated and will be removed in the next major version. You can use this parser by setting parser: "antlr" in your Prettier configuration.

| Default | CLI Override | API Override |
| ------- | ------------------- | -------------------- |
| slang | --parser | parser: "" |

$3

Mimicking prettier's new ternary formatting for the community to try.

Valid options:

- true - Use curious ternaries, with the question mark after the condition.
- false - Retain the default behavior of ternaries; keep question marks on the same line as the consequent.

| Default | CLI Override | API Override |
| ------- | -------------------------- | ------------------------------- |
| false | --experimental-ternaries | experimentalTernaries: |

Integrations

$3

To integrate this plugin with vim, first install vim-prettier. These
instructions assume you are using vim-plug. Add this to your configuration:

`vim
Plug 'prettier/vim-prettier', {
\ 'do': 'yarn install && yarn add prettier-plugin-solidity',
\ 'for': [
\ 'javascript',
\ 'typescript',
\ 'css',
\ 'less',
\ 'scss',
\ 'json',
\ 'graphql',
\ 'markdown',
\ 'vue',
\ 'lua',
\ 'php',
\ 'python',
\ 'ruby',
\ 'html',
\ 'swift',
\ 'solidity'] }
`

We modified the do instruction to also install this plugin. Then you'll have to configure the plugin to always use the version installed in the vim plugin's directory. The vim-plug directory depends on the value you use in call plug#begin('~/.vim/