Skip to content

Latest commit

 

History

History
76 lines (46 loc) · 6.08 KB

CONTRIBUTING.md

File metadata and controls

76 lines (46 loc) · 6.08 KB
Raw

Contributing

Start off forking, then cloning the project locally:

  • $ npm ci - Install dependencies
  • $ npm test - Run tests
  • $ npm run format - Format any changes you've made with prettier
  • $ npm run lint - Check formatting with prettier

Syntax

The syntax is regex based, tools I've been using have include a mix of regex101.com and regexr.com. Note that VSCode does not use JavaScript Regex, but oniguruma instead. They are more compatible with the PCRE flavor in these websites. The Regex in the JSON files are string encoded, so you need to decode/encode them when copying between these websites, you can use a tool like this. You can test your regex with the node version in a scratch pad to see which groups it matches (these may not always be what you expect) https://github.com/atom/node-oniguruma.

It can take some time to get used to the regular expressions.

To visually test your changes press F5 while having this project open in VSCode, it will open another window with extension enabled. You can load the colorize-fixture folder in that window to see your changes.

Refer to JS/TS tokens syntax at https://github.com/microsoft/vscode/tree/master/extensions under <language>/syntaxes/<lang>.tmLanguage.json.

To check how tokens are being matched, select "Developer: Inspect Editor Tokens and Scope" under Command Palette.

"A line break seems to break the syntax highlighting"

Many of the bugs raised are due to multiline regex not being available. Textmate grammar can only match a single line. Unfortunately a lot of the regex we have tries to parse multiple lines at once (which won't work). This has caused bugs to be raised such as: #266 and #277

The best fix is to look at the new line and create a new rule in https://github.com/styled-components/vscode-styled-components/blob/master/syntaxes/styled-components.json which will match that line as close as possible whilst still being generic. Regex101 helps with this.

Intellisense

Intellisense is handled by https://github.com/microsoft/typescript-styled-plugin.

For most things typescript-styled-plugin is just a pass-through to the CSS/SCSS language services. For example, looking at getCompletionItems you can see it just calls the equivalent on the upstream language services. So if something works natively (CSS file), but not in styled-components its most likely because it's not passing the correct events through.

Setting up

img

I use VSCode's multi workspace for this (see above image). I have typescript-styled-plugin, vscode-styled-componentsand vscode-css-languageserver (optional) folders loaded.

You can't run the typescript-styled-plugin directly, instead you need to load a debugger to listen on a port. The below shows you how to set this up so that you can debug both the extension and the plugin at the same time.

  • Make sure typescript-styled-plugin is yarn|npm linked into vscode-styled-components (see image above)
  • uncomment the plugin section in tsconfig, make sure the path points to your local checkout of typescript styled plugin
  • In vscode-styled-components/.vscode/launch.json, "TSS_DEBUG": "9229" should be set (or "TSS_REMOTE_DEBUG": "9229" if using WSL). This allows the debugger to communicate with the typescript-styled-plugin. These may already be set.
  • [Debug Tab] Click Launch extension
  • Once the new window is up and running go back to the host VSCode instance and on the debug tab Click Debug Styled Plugin - This will both build and start the debugger on the typescript-styled-plugin project.

You should now be able to use styled-components in the guest window and set breakpoints on the both the plugin and extension in the main window.

A good starting point is setting a breakpoint here then trying to use completions in the guest window.

[Optional] - If you want to go even deeper and debug the css language server, you will need to yarn|npm link that into typescript plugin and then make sure typescript-plugin's outfiles are also pointing to the css language server's generated files on build.

More Info:

Logging

If you want logging, you can set "typescript.tsserver.log": "verbose" in your global settings (or local guest settings) and view the output, there should be a path to a log file that's printed out. Any console.log you do from the plugin will end up in there.

Tests

You can run tests simply by running npm test. This should spawn another instance of VSCode to run the end to end tests in.

The syntax tests will generate tokens for fixtures we have which are then compared to the results (adjacent folder). If there are changes and the tests fail it will generate a new result (overwriting the previous one).

When making syntax changes you should update the test suite.