magic-string 0 eslint travis-ci npm

Manipulate strings like a wizard

3 years after


build status npm version license dependency status Coverage via Codecov

Suppose you have some source code. You want to make some light modifications to it - replacing a few characters here and there, wrapping it with a header and footer, etc - and ideally you'd like to generate a source map at the end of it. You've thought about using something like recast (which allows you to generate an AST from some JavaScript, manipulate it, and reprint it with a sourcemap without losing your comments and formatting), but it seems like overkill for your needs (or maybe the source code isn't JavaScript).

Your requirements are, frankly, rather niche. But they're requirements that I also have, and for which I made magic-string. It's a small, fast utility for manipulating strings and generating sourcemaps.


magic-string works in both node.js and browser environments. For node, install with npm:

npm i magic-string

To use in browser, grab the magic-string.deps.js file and add it to your page:

<script src='magic-string.deps.js'></script>

(It also works with various module systems, if you prefer that sort of thing - it has a dependency on vlq.)


These examples assume you're in node.js, or something similar:

var MagicString = require( 'magic-string' );
var s = new MagicString( 'problems = 99' );

s.overwrite( 0, 8, 'answer' );
s.toString(); // 'answer = 99'

s.overwrite( 11, 13, '42' ); // character indices always refer to the original string
s.toString(); // 'answer = 42'

s.prepend( 'var ' ).append( ';' ); // most methods are chainable
s.toString(); // 'var answer = 42;'

var map = s.generateMap({
  source: 'source.js',
  file: '',
  includeContent: true
}); // generates a v3 sourcemap

require( 'fs' ).writeFile( 'converted.js', s.toString() );
require( 'fs' ).writeFile( '', map.toString() );

You can pass an options argument:

var s = new MagicString( someCode, {
  // both these options will be used if you later
  // call `bundle.addSource( s )` - see below
  filename: 'foo.js',
  indentExclusionRanges: [/*...*/]


s.addSourcemapLocation( index )

Adds the specified character index (with respect to the original string) to sourcemap mappings, if hires is false (see below).

s.append( content )

Appends the specified content to the end of the string. Returns this.


Does what you'd expect.

s.generateMap( options )

Generates a version 3 sourcemap. All options are, well, optional:

  • file - the filename where you plan to write the sourcemap
  • source - the filename of the file containing the original source
  • includeContent - whether to include the original content in the map's sourcesContent array
  • hires - whether the mapping should be high-resolution. Hi-res mappings map every single character, meaning (for example) your devtools will always be able to pinpoint the exact location of function calls and so on. With lo-res mappings, devtools may only be able to identify the correct line - but they're quicker to generate and less bulky. If sourcemap locations have been specified with s.addSourceMapLocation(), they will be used here.

The returned sourcemap has two (non-enumerable) methods attached for convenience:

  • toString - returns the equivalent of JSON.stringify(map)
  • toUrl - returns a DataURI containing the sourcemap. Useful for doing this sort of thing:
code += '\n//# sourceMappingURL=' + map.toUrl();

s.indent( prefix[, options] )

Prefixes each line of the string with prefix. If prefix is not supplied, the indentation will be guessed from the original content, falling back to a single tab character. Returns this.

The options argument can have an exclude property, which is an array of [start, end] character ranges. These ranges will be excluded from the indentation - useful for (e.g.) multiline strings.

s.insertLeft( index, content )

Inserts the specified content at the index in the original string. If a range ending with index is subsequently moved, the insert will be moved with it. Returns this.

s.insertRight( index, content )

Inserts the specified content at the index in the original string. If a range starting with index is subsequently moved, the insert will be moved with it. Returns this.

s.locate( index )

DEPRECATED since 0.10 – see #30

s.locateOrigin( index )

DEPRECATED since 0.10 – see #30

s.move( start, end, newIndex )

Moves the characters from start and end to index. Returns this.

s.overwrite( start, end, content[, storeName] )

Replaces the characters from start to end with content. The same restrictions as s.remove() apply. Returns this. If storeName is true, the original name will be stored for later inclusion in a sourcemap's names array.

s.prepend( content )

Prepends the string with the specified content. Returns this.

s.remove( start, end )

Removes the characters from start to end (of the original string, not the generated string). Removing the same content twice, or making removals that partially overlap, will cause an error. Returns this.

s.slice( start, end )

Returns the content of the generated string that corresponds to the slice between start and end of the original string. Throws error if the indices are for characters that were already removed.

s.snip( start, end )

Returns a clone of s, with all content before the start and end characters of the original string removed.


Returns the generated string.

s.trim([ charType ])

Trims content matching charType (defaults to \s, i.e. whitespace) from the start and end. Returns this.

s.trimStart([ charType ])

Trims content matching charType (defaults to \s, i.e. whitespace) from the start. Returns this.

s.trimEnd([ charType ])

Trims content matching charType (defaults to \s, i.e. whitespace) from the end. Returns this.


Removes empty lines from the start and end. Returns this.


To concatenate several sources, use MagicString.Bundle:

var bundle = new MagicString.Bundle();

  filename: 'foo.js',
  content: new MagicString( 'var answer = 42;' )

  filename: 'bar.js',
  content: new MagicString( 'console.log( answer )' )

// Advanced: a source can include an `indentExclusionRanges` property
// alongside `filename` and `content`. This will be passed to `s.indent()`
// - see documentation above

bundle.indent() // optionally, pass an indent string, otherwise it will be guessed
  .prepend( '(function () {\n' )
  .append( '}());' );

// (function () {
//   var answer = 42;
//   console.log( answer );
// }());

// options are as per `s.generateMap()` above
var map = bundle.generateMap({
  file: 'bundle.js',
  includeContent: true,
  hires: true

As an alternative syntax, if you a) don't have filename or indentExclusionRanges options, or b) passed those in when you used new MagicString(...), you can simply pass the MagicString instance itself:

var bundle = new MagicString.Bundle();
var source = new MagicString( someCode, {
  filename: 'foo.js'

bundle.addSource( source );



Related Repositories



A library designed to make it easy to use Google App Engine from Clojure ...



API for Magic: The Gathering cards, cached from Gatherer ...



PHP 5.3 OOP String Manipulation ...



Build virtual tree elements with magic attributes ...



Help Ios/Android to generate localize string file ...

Top Contributors

Rich-Harris greenkeeperio-bot TrySound eventualbuddha leebyron alangpierce Permutatrix tricknotes


package version
vlq ^0.2.1
dev buble ^0.14.0 ^0.1.6
console-group ^0.3.2
eslint ^3.7.1
istanbul ^0.4.5
mocha ^3.1.0
remap-istanbul ^0.6.4
resolve ^1.1.7
rollup ^0.36.1
rollup-plugin-buble ^0.14.0
rollup-plugin-node-resolve ^2.0.0
rollup-plugin-replace ^1.1.1
source-map ^0.5.6
source-map-support ^0.4.3


-   v0.16.0 zip tar
-   v0.15.2 zip tar
-   v0.15.1 zip tar
-   v0.15.0 zip tar
-   v0.14.0 zip tar
-   v0.13.1 zip tar
-   v0.13.0 zip tar
-   v0.12.1 zip tar
-   v0.12.0 zip tar
-   v0.11.4 zip tar
-   v0.11.3 zip tar
-   v0.11.2 zip tar
-   v0.11.1 zip tar
-   v0.10.2 zip tar
-   v0.10.1 zip tar
-   v0.9.1 zip tar
-   v0.9.0 zip tar
-   v0.8.0 zip tar
-   v0.6.6 zip tar
-   v0.6.5 zip tar
-   v0.6.4 zip tar
-   v0.6.3 zip tar
-   v0.6.2 zip tar
-   v0.6.1 zip tar
-   v0.6.0 zip tar
-   v0.5.3 zip tar
-   v0.5.1 zip tar
-   v0.5.0 zip tar
-   v0.1.6 zip tar