svelte-codemirror-component

a simple CodeMirror component for Svelte

This module implements a simple Svelte component with a configurable CodeMirror 5 instance. It is based on a simpilar component which is part of the Svelte REPL and a Svelte REPL example.

Nota bene: like many other Svelte components, this one may also be used outside Svelte in a normal HTML document - see Usage outside Svelte for details.

NPM users: please consider the Github README for the latest description of this package (as updating the docs would otherwise always require a new NPM package version)

Just a small note: if you like this module and plan to use it, consider "starring" this repository (you will find the "Star" button on the top right of this page), so that I know which of my repositories to take most care of.

Installation

npm install svelte-codemirror-component

Usage

svelte-codemirror-component should be imported in a module context and may then be used in your markup:

<script context="module">
  import CodeMirrorComponent from 'svelte-codemirror-component'
</script>

<CodeMirrorComponent/>

Warning: as I have not yet been able to bundle JSHint, JSONLint and CSSLint, you will have to import them yourself if you plan to use syntax checking for JavaScript, JSON or CSS files:

<svelte:head>
  <script src="https://cdnjs.cloudflare.com/ajax/libs/jshint/2.13.4/jshint.min.js"></script>
  <script src="https://cdnjs.cloudflare.com/ajax/libs/jsonlint/1.6.0/jsonlint.min.js"></script>
  <script src="https://cdnjs.cloudflare.com/ajax/libs/csslint/1.0.5/csslint.min.js"></script>
</svelte:head>

<script context="module">
  import CodeMirrorComponent from 'svelte-codemirror-component'
</script>

<CodeMirrorComponent Mode='js'/>

If you are sensitive to the GDPR (or similar regulations) you should probably first copy the mentioned JavaScript files to your local server and reference them from there.

Bindings

svelte-codemirror-component offers two bindings which give you direct access to the underlying CodeMirror instance and the current value of the edited text:

• Editor
  allows to address the CodeMirror instance directly (which might be useful if you plan to react on CodeMirror events)
• Value
  "reactively" binds to the currently edited text

<script context="module">
  import CodeMirrorComponent from 'svelte-codemirror-component'
</script>

<script >
  let Editor, Value = 'initial Value'
  
  $: console.log('new Value',Value)
</script>

<CodeMirrorComponent bind:Editor={Editor} bind:Value={Value}/>

Options and Bindings

The CodeMirror component already defines a few simple options itself - in addition to an Options attribute which may be used to pass any (other) options directly to the CodeMirror instance. Options will only be considered during component instantiation - later changes will be ignored.

• Mode
  specifies the language mode CodeMirror is working in. You may specify either js (for JavaScript), svelte, json, html, css or yaml - by default, Mode is set to js
• LintOptions
  by default, texts edited in mode js, json, html or css are "linted", i.e., any syntactic errors are indicated as such in the "gutter" area to the left of the incorrect line. You may alternatively specify an object with specific options for the chosen linter - or simply disable linting by setting it to false
• withLineNumbers
  set this option to true (which is also the default) in order to show line numbers in the "gutter area" to the left of the edited text - or to false otherwise
• withLineWrapping
  set this option to true in order to let long lines be wrapped - or to false otherwise (false is the default)
• Indentation
  specifies the number of characters a new line should be indented automatically after the beginning of a new JavaScript or JSON block or list (i.e., after { or [) or a new HTML tag (i.e., after <). By default, it is set to 2
• TabSize
  specifies the number of characters a horizontal tab should proceed (by default, the tab size is set to 2)
• indentWithTabs
  set this to true if you want tabs to be preserved - or false if you prefer spaces instead of tabs (by default, this option is set to false, i.e., spaces are preferred)
• closeBrackets
  set this to true if you want CodeMirror to automatically insert a closing brace for you whenever you enter an opening one - or false otherwise (by default, no closing bracket is inserted)
• closeTags
  set this to true if you want CodeMirror to automatically insert a closing > for you whenever you enter a < in HTML mode - or false otherwise (by default, opened tags are not automatically closed)

Events

Right now, only one type of CodeMirror event is passed through to the user of a CodeMirror component:

• change
  this event is fired whenever the edited text changes. You may catch it like any other Svelte event:
  <CodeMirrorComponent on:change={your-event-handler}/>

Styling

The visual appearance of CodeMirror components may be adjusted by specifying styles for the CSS classes which have been assigned to the various parts of a CodeMirror instance. You should, however, take care to use rather specific CSS selectors in order to override the internal defaults. In the easiest case, you may just assign your own CSS class to a CodeMirror component and mention that in your stylesheet:

<style>
  :global(.my .CodeMirror) {
    height:100%; /* to overwrite internal default settings */
    background:white;
    font-family:Courier,"Lucida Console",Monaco,monospace;
    font-size:14px; font-weight:normal;
    color:black;
  }
</style>

<script context="module" lang="ts">
  import CodeMirrorComponent from 'svelte-codemirror-component'
</script>

<CodeMirrorComponent class="my" style="width:480px; height:300px; border:solid 1px gray"
  Value='console.log("Hello, World!")' Mode='js'/>

Usage outside Svelte

The (bundled version of the) CodeMirror component may also be used outside Svelte in a normal HTML page as shown in a separate example. Just load the bundled version together with any desired linters and insert it into a given DOM element:

<!DOCTYPE html>
<html>
 <head>
  <script src="https://cdnjs.cloudflare.com/ajax/libs/jshint/2.13.4/jshint.min.js"></script>
  <script src="https://unpkg.com/svelte-codemirror-component@latest/dist/svelte-codemirror-component.bundled.js"></script>
  <script>
    document.addEventListener("DOMContentLoaded", function () {
      let JSValue  = `console.log('Hello, World!')`
      let JSEditor = new CodeMirrorComponent({
        target: document.getElementById('JS-Editor'),
        props: {
          Value:JSValue, Mode:'js',
          style:'width:480px; height:320px; border:solid 1px; overflow:auto'
        }
      })
  </script>
 </head>
 <body>
  <div id="JS-Editor"></div>
 </body>
</html>

Build Instructions

You may easily build this package yourself.

Just install NPM according to the instructions for your platform and follow these steps:

1. either clone this repository using git or download a ZIP archive with its contents to your disk and unpack it there
2. open a shell and navigate to the root directory of this repository
3. run npm install in order to install the complete build environment
4. execute npm run build to create a new build

You may also look into the author's build-configuration-study for a general description of his build environment.

License

MIT License