@sveltejs/sv-utils is an add-on utility for parsing, transforming, and generating code..
npm install - D @sveltejs / sv - utils transforms is a collection of parser-aware functions that lets you modify the files via abstract syntax tree (AST). It accepts a callback function. The return value is designed to be be passed directly into sv.file(). The parser choice is baked into the transform type - you can’t accidentally parse a vite config as Svelte because you never call a parser yourself.
Each transform injects relevant utilities into the callback, so you only need one import:
import { transforms ( alias ) namespace transforms
import transforms } from '@sveltejs/sv-utils' ;
transforms ( alias ) namespace transforms
import transforms . script ( alias ) transforms_d_exports . script ( cb : ( file : {
ast : Program ;
comments : Comments ;
content : string ;
js : typeof index_d_exports$3 ;
}) => void | false , options ? : TransformOptions ): transforms . TransformFn
export transforms_d_exports . script Transform a JavaScript/TypeScript file.
Return false from the callback to abort.
( );
transforms ( alias ) namespace transforms
import transforms . svelte ( alias ) transforms_d_exports . svelte ( cb : ( file : {
ast : AST . Root ;
content : string ;
svelte : typeof index_d_exports$4 ;
js : typeof index_d_exports$3 ;
}) => void | false , options ? : TransformOptions ): transforms . TransformFn
export transforms_d_exports . svelte Transform a Svelte component file.
Return false from the callback to abort.
( );
Transform a JavaScript/TypeScript file. The callback receives { ast, comments, content, js }.
import { transforms ( alias ) namespace transforms
import transforms } from '@sveltejs/sv-utils' ;
sv any . file any (
file any . viteConfig any ,
transforms ( alias ) namespace transforms
import transforms . script ( alias ) transforms_d_exports . script ( cb : ( file : {
ast : Program ;
comments : Comments ;
content : string ;
js : typeof index_d_exports$3 ;
}) => void | false , options ? : TransformOptions ): transforms . TransformFn
export transforms_d_exports . script Transform a JavaScript/TypeScript file.
Return false from the callback to abort.
(({ ast ( parameter ) ast : Program , js ( parameter ) js : typeof index_d_exports$3 }) => {
js ( parameter ) js : typeof index_d_exports$3 . imports ( alias ) namespace index_d_exports$3 . imports
export index_d_exports$3 . imports . addDefault ( alias ) imports_d_exports . addDefault ( node : Program , options : {
from : string ;
as : string ;
}): void
export imports_d_exports . addDefault ( ast ( parameter ) ast : Program , { as ( property ) as : string : 'foo' , from ( property ) from : string : 'foo' });
js ( parameter ) js : typeof index_d_exports$3 . vite ( alias ) namespace index_d_exports$3 . vite
export index_d_exports$3 . vite . addPlugin ( alias ) vite_d_exports . addPlugin ( ast : Program , options : {
code : string ;
mode ? : "append" | "prepend" ;
}): void
export vite_d_exports . addPlugin ( ast ( parameter ) ast : Program , { code ( property ) code : string : 'foo()' });
})
); Transform a Svelte component. The callback receives { ast, content, svelte, js }.
import { transforms ( alias ) namespace transforms
import transforms } from '@sveltejs/sv-utils' ;
sv any . file any (
layoutPath any ,
transforms ( alias ) namespace transforms
import transforms . svelte ( alias ) transforms_d_exports . svelte ( cb : ( file : {
ast : AST . Root ;
content : string ;
svelte : typeof index_d_exports$4 ;
js : typeof index_d_exports$3 ;
}) => void | false , options ? : TransformOptions ): transforms . TransformFn
export transforms_d_exports . svelte Transform a Svelte component file.
Return false from the callback to abort.
(({ ast ( parameter ) ast : AST . Root , svelte ( parameter ) svelte : typeof index_d_exports$4 }) => {
svelte ( parameter ) svelte : typeof index_d_exports$4 . addFragment ( alias ) index_d_exports$4 . addFragment ( ast : AST . Root | AST . BaseElement , content : string , options ? : {
mode ? : "append" | "prepend" ;
language ? : "ts" | "js" ;
}): void
export index_d_exports$4 . addFragment ( ast ( parameter ) ast : AST . Root , '<Foo />' );
})
); Transform a Svelte component with a <script> block guaranteed. Pass { language } as the first argument. The callback receives { ast, content, svelte, js } where ast.instance is always non-null.
import { transforms ( alias ) namespace transforms
import transforms } from '@sveltejs/sv-utils' ;
sv any . file any (
layoutPath any ,
transforms ( alias ) namespace transforms
import transforms . svelteScript ( alias ) transforms_d_exports . svelteScript ( scriptOptions : {
language : "ts" | "js" ;
}, cb : ( file : {
ast : RootWithInstance ;
content : string ;
svelte : typeof index_d_exports$4 ;
js : typeof index_d_exports$3 ;
}) => void | false , options ? : TransformOptions ): transforms . TransformFn
export transforms_d_exports . svelteScript Transform a Svelte component file with a script block guaranteed.
Calls ensureScript before invoking your callback, so ast.instance is always non-null.
Pass { language } as the first argument to set the script language.
Return false from the callback to abort.
({ language ( property ) language : "ts" | "js" : 'ts' }, ({ ast ( parameter ) ast : RootWithInstance , svelte ( parameter ) svelte : typeof index_d_exports$4 , js ( parameter ) js : typeof index_d_exports$3 }) => {
js ( parameter ) js : typeof index_d_exports$3 . imports ( alias ) namespace index_d_exports$3 . imports
export index_d_exports$3 . imports . addDefault ( alias ) imports_d_exports . addDefault ( node : Program , options : {
from : string ;
as : string ;
}): void
export imports_d_exports . addDefault ( ast ( parameter ) ast : RootWithInstance . instance ( property ) instance : AST . Script The parsed <script> element, if exists
. content ( property ) AST . Script . content : Program , { as ( property ) as : string : 'Foo' , from ( property ) from : string : './Foo.svelte' });
svelte ( parameter ) svelte : typeof index_d_exports$4 . addFragment ( alias ) index_d_exports$4 . addFragment ( ast : AST . Root | AST . BaseElement , content : string , options ? : {
mode ? : "append" | "prepend" ;
language ? : "ts" | "js" ;
}): void
export index_d_exports$4 . addFragment ( ast ( parameter ) ast : RootWithInstance , '<Foo />' );
})
); Transform a CSS file. The callback receives { ast, content, css }.
import { transforms ( alias ) namespace transforms
import transforms } from '@sveltejs/sv-utils' ;
sv any . file any (
file any . stylesheet any ,
transforms ( alias ) namespace transforms
import transforms . css ( alias ) transforms_d_exports . css ( cb : ( file : {
ast : Omit < _CSS . StyleSheetBase , "attributes" | "content" > ;
content : string ;
css : typeof index_d_exports$1 ;
}) => void | false , options ? : TransformOptions ): transforms . TransformFn
export transforms_d_exports . css Transform a CSS file.
Return false from the callback to abort.
(({ ast ( parameter ) ast : Omit < _CSS . StyleSheetBase , "attributes" | "content" > , css ( parameter ) css : typeof index_d_exports$1 }) => {
css ( parameter ) css : typeof index_d_exports$1 . addAtRule ( alias ) index_d_exports$1 . addAtRule ( node : _CSS . StyleSheetBase , options : {
name : string ;
params : string ;
append : boolean ;
}): _CSS . Atrule
export index_d_exports$1 . addAtRule ( ast ( parameter ) ast : Omit < _CSS . StyleSheetBase , "attributes" | "content" > , { name ( property ) name : string : 'import' , params ( property ) params : string : "'tailwindcss'" });
})
); Transform a JSON file. Mutate the data object directly. The callback receives { data, content, json }.
import { transforms ( alias ) namespace transforms
import transforms } from '@sveltejs/sv-utils' ;
sv any . file any (
file any . typeConfig any ,
transforms ( alias ) namespace transforms
import transforms . json ( alias ) transforms_d_exports . json < any > ( cb : ( file : {
data : any ;
content : string ;
json : typeof json_d_exports ;
}) => void | false , options ? : TransformOptions ): transforms . TransformFn
export transforms_d_exports . json Transform a JSON file.
Return false from the callback to abort.
(({ data ( parameter ) data : any }) => {
data ( parameter ) data : any . compilerOptions any ??= {};
data ( parameter ) data : any . compilerOptions any . strict any = true ;
})
); Same pattern as transforms.json, for YAML and TOML files respectively. The callback receives { data, content }.
transforms.text Transform a plain text file (.env, .gitignore, etc.). No parser - string in, string out. The callback receives { content, text }.
import { transforms ( alias ) namespace transforms
import transforms } from '@sveltejs/sv-utils' ;
sv any . file any (
'.env' ,
transforms ( alias ) namespace transforms
import transforms . text ( alias ) transforms_d_exports . text ( cb : ( file : {
content : string ;
text : typeof text_d_exports ;
}) => string | false ): transforms . TransformFn
export transforms_d_exports . text Transform a plain text file (.env, .gitignore, etc.).
Unlike other transforms there's no AST here - just string in, string out.
Return the new content, or false to abort (original content is returned unchanged).
(({ content ( parameter ) content : string }) => {
return content ( parameter ) content : string + ' \n DATABASE_URL="file:local.db"' ;
})
); Return false from any transform callback to abort - the original content is returned unchanged.
import { transforms ( alias ) namespace transforms
import transforms } from '@sveltejs/sv-utils' ;
sv any . file any (
'eslint.config.js' ,
transforms ( alias ) namespace transforms
import transforms . script ( alias ) transforms_d_exports . script ( cb : ( file : {
ast : Program ;
comments : Comments ;
content : string ;
js : typeof index_d_exports$3 ;
}) => void | false , options ? : TransformOptions ): transforms . TransformFn
export transforms_d_exports . script Transform a JavaScript/TypeScript file.
Return false from the callback to abort.
(({ ast ( parameter ) ast : Program , js ( parameter ) js : typeof index_d_exports$3 }) => {
const { value ( property ) value : any : existing const existing : any } = js ( parameter ) js : typeof index_d_exports$3 . exports ( alias ) namespace index_d_exports$3 . exports
export index_d_exports$3 . exports . createDefault ( alias ) exports_d_exports . createDefault < any > ( node : Program , options : {
fallback : any ;
}): ExportDefaultResult < any >
export exports_d_exports . createDefault ( ast ( parameter ) ast : Program , { fallback ( property ) fallback : any : myConfig any });
if ( existing const existing : any !== myConfig any ) {
return false ;
}
})
); Transforms are curried functions - call them with the callback, then apply to content:
import { transforms ( alias ) namespace transforms
import transforms } from '@sveltejs/sv-utils' ;
const transform const transform : transforms . TransformFn = transforms ( alias ) namespace transforms
import transforms . script ( alias ) transforms_d_exports . script ( cb : ( file : {
ast : Program ;
comments : Comments ;
content : string ;
js : typeof index_d_exports$3 ;
}) => void | false , options ? : TransformOptions ): transforms . TransformFn
export transforms_d_exports . script Transform a JavaScript/TypeScript file.
Return false from the callback to abort.
(({ ast ( parameter ) ast : Program , js ( parameter ) js : typeof index_d_exports$3 }) => {
js ( parameter ) js : typeof index_d_exports$3 . imports ( alias ) namespace index_d_exports$3 . imports
export index_d_exports$3 . imports . addDefault ( alias ) imports_d_exports . addDefault ( node : Program , options : {
from : string ;
as : string ;
}): void
export imports_d_exports . addDefault ( ast ( parameter ) ast : Program , { as ( property ) as : string : 'foo' , from ( property ) from : string : 'foo' });
});
const result const result : string | false = transform const transform : ( content : string ) => string | false ( 'export default {}' ); For cases where you need to mix and match transforms and raw edits, use sv.file with a content callback and invoke the curried transform manually:
sv any . file any ( path any , ( content ( parameter ) content : any ) => {
const transform const transform : any = transforms any . script any (({ ast ( parameter ) ast : any , js ( parameter ) js : any }) => {
js ( parameter ) js : any . imports any . addDefault any ( ast ( parameter ) ast : any , { as ( property ) as : string : 'foo' , from ( property ) from : string : 'bar' });
});
content ( parameter ) content : any = transform const transform : any ( content ( parameter ) content : any );
content ( parameter ) content : any = content ( parameter ) content : any . replace any ( 'foo' , 'baz' );
return content ( parameter ) content : any ;
}); Add-ons can also export reusable transform functions:
import { transforms ( alias ) namespace transforms
import transforms } from '@sveltejs/sv-utils' ;
export const addFooImport const addFooImport : transforms . TransformFn = transforms ( alias ) namespace transforms
import transforms . svelte ( alias ) transforms_d_exports . svelte ( cb : ( file : {
ast : AST . Root ;
content : string ;
svelte : typeof index_d_exports$4 ;
js : typeof index_d_exports$3 ;
}) => void | false , options ? : TransformOptions ): transforms . TransformFn
export transforms_d_exports . svelte Transform a Svelte component file.
Return false from the callback to abort.
(({ ast ( parameter ) ast : AST . Root , svelte ( parameter ) svelte : typeof index_d_exports$4 , js ( parameter ) js : typeof index_d_exports$3 }) => {
svelte ( parameter ) svelte : typeof index_d_exports$4 . ensureScript ( alias ) index_d_exports$4 . ensureScript ( ast : AST . Root , options ? : {
language ? : "ts" | "js" ;
}): asserts ast is RootWithInstance
export index_d_exports$4 . ensureScript ( ast ( parameter ) ast : AST . Root , { language ( property ) language ? : "js" | "ts" | undefined });
js ( parameter ) js : typeof index_d_exports$3 . imports ( alias ) namespace index_d_exports$3 . imports
export index_d_exports$3 . imports . addDefault ( alias ) imports_d_exports . addDefault ( node : Program , options : {
from : string ;
as : string ;
}): void
export imports_d_exports . addDefault ( ast ( parameter ) ast : AST . Root . instance ( property ) AST . Root . instance : AST . Script | null The parsed <script> element, if exists
. content ( property ) AST . Script . content : Program , { as ( property ) as : string : 'Foo' , from ( property ) from : string : './Foo.svelte' });
});
sv any . file any ( '+page.svelte' , addFooImport any );
sv any . file any ( 'index.svelte' , addFooImport any ); Parsers (low-level) transforms will fit most users needs (e.g., conditional parsing, error handling around the parser). If not, parse is a low-level API available to you:
import { parse ( alias ) const parse : {
css : ( source : string ) => {
ast : Omit < _CSS . StyleSheetBase , "attributes" | "content" > ;
} & ParseBase ;
html : ( source : string ) => {
ast : AST . Fragment ;
} & ParseBase ;
json : ( source : string ) => {
data : any ;
} & ParseBase ;
script : ( source : string ) => {
ast : Program ;
comments : Comments ;
} & ParseBase ;
svelte : ( source : string ) => {
ast : AST . Root ;
} & ParseBase ;
toml : ( source : string ) => {
data : TomlTable ;
} & ParseBase ;
yaml : ( source : string ) => {
data : YamlDocument ;
} & ParseBase ;
}
import parse Low-level parsers. Prefer transforms for add-on file edits — it picks the
right parser for you and handles generateCode() automatically.
Use parse directly when you need error handling around parsing or
conditional parser selection at runtime.
import { parse } from '@sveltejs/sv-utils' ;
const { ast , generateCode } = parse . script ( 'function add(a, b) { return a + b; }' );
const { ast , generateCode } = parse . svelte ( '<div>Hello, world!</div>' );
const { ast , generateCode } = parse . css ( 'body { color: red; }' );
const { data , generateCode } = parse . json ( '{ "name": "John", "age": 30 }' );
const { data , generateCode } = parse . yaml ( 'name: John' );
const { data , generateCode } = parse . toml ( 'name = "John"' );
const { ast , generateCode } = parse . html ( '<div>Hello, world!</div>' ); } from '@sveltejs/sv-utils' ;
const { ast const ast : Program , generateCode const generateCode : () => string Generate the code after manipulating the ast.
Regenerate code from the modified AST
Output source code from the manipulated ast
} = parse ( alias ) const parse : {
css : ( source : string ) => {
ast : Omit < _CSS . StyleSheetBase , "attributes" | "content" > ;
} & ParseBase ;
html : ( source : string ) => {
ast : AST . Fragment ;
} & ParseBase ;
json : ( source : string ) => {
data : any ;
} & ParseBase ;
script : ( source : string ) => {
ast : Program ;
comments : Comments ;
} & ParseBase ;
svelte : ( source : string ) => {
ast : AST . Root ;
} & ParseBase ;
toml : ( source : string ) => {
data : TomlTable ;
} & ParseBase ;
yaml : ( source : string ) => {
data : YamlDocument ;
} & ParseBase ;
}
import parse Low-level parsers. Prefer transforms for add-on file edits — it picks the
right parser for you and handles generateCode() automatically.
Use parse directly when you need error handling around parsing or
conditional parser selection at runtime.
import { parse } from '@sveltejs/sv-utils' ;
const { ast , generateCode } = parse . script ( 'function add(a, b) { return a + b; }' );
const { ast , generateCode } = parse . svelte ( '<div>Hello, world!</div>' );
const { ast , generateCode } = parse . css ( 'body { color: red; }' );
const { data , generateCode } = parse . json ( '{ "name": "John", "age": 30 }' );
const { data , generateCode } = parse . yaml ( 'name: John' );
const { data , generateCode } = parse . toml ( 'name = "John"' );
const { ast , generateCode } = parse . html ( '<div>Hello, world!</div>' ); . script ( property ) script : ( source : string ) => {
ast : Program ;
comments : Comments ;
} & ParseBase ( content any );
const { ast const ast : AST . Root , generateCode const generateCode : () => string Generate the code after manipulating the ast.
Regenerate code from the modified AST
Output source code from the manipulated ast
} = parse ( alias ) const parse : {
css : ( source : string ) => {
ast : Omit < _CSS . StyleSheetBase , "attributes" | "content" > ;
} & ParseBase ;
html : ( source : string ) => {
ast : AST . Fragment ;
} & ParseBase ;
json : ( source : string ) => {
data : any ;
} & ParseBase ;
script : ( source : string ) => {
ast : Program ;
comments : Comments ;
} & ParseBase ;
svelte : ( source : string ) => {
ast : AST . Root ;
} & ParseBase ;
toml : ( source : string ) => {
data : TomlTable ;
} & ParseBase ;
yaml : ( source : string ) => {
data : YamlDocument ;
} & ParseBase ;
}
import parse Low-level parsers. Prefer transforms for add-on file edits — it picks the
right parser for you and handles generateCode() automatically.
Use parse directly when you need error handling around parsing or
conditional parser selection at runtime.
import { parse } from '@sveltejs/sv-utils' ;
const { ast , generateCode } = parse . script ( 'function add(a, b) { return a + b; }' );
const { ast , generateCode } = parse . svelte ( '<div>Hello, world!</div>' );
const { ast , generateCode } = parse . css ( 'body { color: red; }' );
const { data , generateCode } = parse . json ( '{ "name": "John", "age": 30 }' );
const { data , generateCode } = parse . yaml ( 'name: John' );
const { data , generateCode } = parse . toml ( 'name = "John"' );
const { ast , generateCode } = parse . html ( '<div>Hello, world!</div>' ); . svelte ( property ) svelte : ( source : string ) => {
ast : AST . Root ;
} & ParseBase ( content any );
const { ast const ast : Omit < _CSS . StyleSheetBase , "attributes" | "content" > , generateCode const generateCode : () => string Generate the code after manipulating the ast.
Regenerate code from the modified AST
Output source code from the manipulated ast
} = parse ( alias ) const parse : {
css : ( source : string ) => {
ast : Omit < _CSS . StyleSheetBase , "attributes" | "content" > ;
} & ParseBase ;
html : ( source : string ) => {
ast : AST . Fragment ;
} & ParseBase ;
json : ( source : string ) => {
data : any ;
} & ParseBase ;
script : ( source : string ) => {
ast : Program ;
comments : Comments ;
} & ParseBase ;
svelte : ( source : string ) => {
ast : AST . Root ;
} & ParseBase ;
toml : ( source : string ) => {
data : TomlTable ;
} & ParseBase ;
yaml : ( source : string ) => {
data : YamlDocument ;
} & ParseBase ;
}
import parse Low-level parsers. Prefer transforms for add-on file edits — it picks the
right parser for you and handles generateCode() automatically.
Use parse directly when you need error handling around parsing or
conditional parser selection at runtime.
import { parse } from '@sveltejs/sv-utils' ;
const { ast , generateCode } = parse . script ( 'function add(a, b) { return a + b; }' );
const { ast , generateCode } = parse . svelte ( '<div>Hello, world!</div>' );
const { ast , generateCode } = parse . css ( 'body { color: red; }' );
const { data , generateCode } = parse . json ( '{ "name": "John", "age": 30 }' );
const { data , generateCode } = parse . yaml ( 'name: John' );
const { data , generateCode } = parse . toml ( 'name = "John"' );
const { ast , generateCode } = parse . html ( '<div>Hello, world!</div>' ); . css ( property ) css : ( source : string ) => {
ast : Omit < _CSS . StyleSheetBase , "attributes" | "content" > ;
} & ParseBase ( content any );
const { data const data : any , generateCode const generateCode : () => string Generate the code after manipulating the ast.
Regenerate code from the modified AST
Output source code from the manipulated ast
} = parse ( alias ) const parse : {
css : ( source : string ) => {
ast : Omit < _CSS . StyleSheetBase , "attributes" | "content" > ;
} & ParseBase ;
html : ( source : string ) => {
ast : AST . Fragment ;
} & ParseBase ;
json : ( source : string ) => {
data : any ;
} & ParseBase ;
script : ( source : string ) => {
ast : Program ;
comments : Comments ;
} & ParseBase ;
svelte : ( source : string ) => {
ast : AST . Root ;
} & ParseBase ;
toml : ( source : string ) => {
data : TomlTable ;
} & ParseBase ;
yaml : ( source : string ) => {
data : YamlDocument ;
} & ParseBase ;
}
import parse Low-level parsers. Prefer transforms for add-on file edits — it picks the
right parser for you and handles generateCode() automatically.
Use parse directly when you need error handling around parsing or
conditional parser selection at runtime.
import { parse } from '@sveltejs/sv-utils' ;
const { ast , generateCode } = parse . script ( 'function add(a, b) { return a + b; }' );
const { ast , generateCode } = parse . svelte ( '<div>Hello, world!</div>' );
const { ast , generateCode } = parse . css ( 'body { color: red; }' );
const { data , generateCode } = parse . json ( '{ "name": "John", "age": 30 }' );
const { data , generateCode } = parse . yaml ( 'name: John' );
const { data , generateCode } = parse . toml ( 'name = "John"' );
const { ast , generateCode } = parse . html ( '<div>Hello, world!</div>' ); . json ( property ) json : ( source : string ) => {
data : any ;
} & ParseBase ( content any );
const { data const data : YamlDocument , generateCode const generateCode : () => string Generate the code after manipulating the ast.
Regenerate code from the modified AST
Output source code from the manipulated ast
} = parse ( alias ) const parse : {
css : ( source : string ) => {
ast : Omit < _CSS . StyleSheetBase , "attributes" | "content" > ;
} & ParseBase ;
html : ( source : string ) => {
ast : AST . Fragment ;
} & ParseBase ;
json : ( source : string ) => {
data : any ;
} & ParseBase ;
script : ( source : string ) => {
ast : Program ;
comments : Comments ;
} & ParseBase ;
svelte : ( source : string ) => {
ast : AST . Root ;
} & ParseBase ;
toml : ( source : string ) => {
data : TomlTable ;
} & ParseBase ;
yaml : ( source : string ) => {
data : YamlDocument ;
} & ParseBase ;
}
import parse Low-level parsers. Prefer transforms for add-on file edits — it picks the
right parser for you and handles generateCode() automatically.
Use parse directly when you need error handling around parsing or
conditional parser selection at runtime.
import { parse } from '@sveltejs/sv-utils' ;
const { ast , generateCode } = parse . script ( 'function add(a, b) { return a + b; }' );
const { ast , generateCode } = parse . svelte ( '<div>Hello, world!</div>' );
const { ast , generateCode } = parse . css ( 'body { color: red; }' );
const { data , generateCode } = parse . json ( '{ "name": "John", "age": 30 }' );
const { data , generateCode } = parse . yaml ( 'name: John' );
const { data , generateCode } = parse . toml ( 'name = "John"' );
const { ast , generateCode } = parse . html ( '<div>Hello, world!</div>' ); . yaml ( property ) yaml : ( source : string ) => {
data : YamlDocument ;
} & ParseBase ( content any );
const { data const data : TomlTable , generateCode const generateCode : () => string Generate the code after manipulating the ast.
Regenerate code from the modified AST
Output source code from the manipulated ast
} = parse ( alias ) const parse : {
css : ( source : string ) => {
ast : Omit < _CSS . StyleSheetBase , "attributes" | "content" > ;
} & ParseBase ;
html : ( source : string ) => {
ast : AST . Fragment ;
} & ParseBase ;
json : ( source : string ) => {
data : any ;
} & ParseBase ;
script : ( source : string ) => {
ast : Program ;
comments : Comments ;
} & ParseBase ;
svelte : ( source : string ) => {
ast : AST . Root ;
} & ParseBase ;
toml : ( source : string ) => {
data : TomlTable ;
} & ParseBase ;
yaml : ( source : string ) => {
data : YamlDocument ;
} & ParseBase ;
}
import parse Low-level parsers. Prefer transforms for add-on file edits — it picks the
right parser for you and handles generateCode() automatically.
Use parse directly when you need error handling around parsing or
conditional parser selection at runtime.
import { parse } from '@sveltejs/sv-utils' ;
const { ast , generateCode } = parse . script ( 'function add(a, b) { return a + b; }' );
const { ast , generateCode } = parse . svelte ( '<div>Hello, world!</div>' );
const { ast , generateCode } = parse . css ( 'body { color: red; }' );
const { data , generateCode } = parse . json ( '{ "name": "John", "age": 30 }' );
const { data , generateCode } = parse . yaml ( 'name: John' );
const { data , generateCode } = parse . toml ( 'name = "John"' );
const { ast , generateCode } = parse . html ( '<div>Hello, world!</div>' ); . toml ( property ) toml : ( source : string ) => {
data : TomlTable ;
} & ParseBase ( content any );
const { ast const ast : AST . Fragment , generateCode const generateCode : () => string Generate the code after manipulating the ast.
Regenerate code from the modified AST
Output source code from the manipulated ast
} = parse ( alias ) const parse : {
css : ( source : string ) => {
ast : Omit < _CSS . StyleSheetBase , "attributes" | "content" > ;
} & ParseBase ;
html : ( source : string ) => {
ast : AST . Fragment ;
} & ParseBase ;
json : ( source : string ) => {
data : any ;
} & ParseBase ;
script : ( source : string ) => {
ast : Program ;
comments : Comments ;
} & ParseBase ;
svelte : ( source : string ) => {
ast : AST . Root ;
} & ParseBase ;
toml : ( source : string ) => {
data : TomlTable ;
} & ParseBase ;
yaml : ( source : string ) => {
data : YamlDocument ;
} & ParseBase ;
}
import parse Low-level parsers. Prefer transforms for add-on file edits — it picks the
right parser for you and handles generateCode() automatically.
Use parse directly when you need error handling around parsing or
conditional parser selection at runtime.
import { parse } from '@sveltejs/sv-utils' ;
const { ast , generateCode } = parse . script ( 'function add(a, b) { return a + b; }' );
const { ast , generateCode } = parse . svelte ( '<div>Hello, world!</div>' );
const { ast , generateCode } = parse . css ( 'body { color: red; }' );
const { data , generateCode } = parse . json ( '{ "name": "John", "age": 30 }' );
const { data , generateCode } = parse . yaml ( 'name: John' );
const { data , generateCode } = parse . toml ( 'name = "John"' );
const { ast , generateCode } = parse . html ( '<div>Hello, world!</div>' ); . html ( property ) html : ( source : string ) => {
ast : AST . Fragment ;
} & ParseBase ( content any ); Namespaced helpers for AST manipulation:
js.* - imports, exports, objects, arrays, variables, functions, vite config helpers, SvelteKit helpers
css.* - rules, declarations, at-rules, imports
svelte.* - ensureScript, addSlot, addFragment
json.* - arrayUpsert, packageScriptsUpsert
html.* - attribute manipulation
text.* - upsert lines in flat files (.env, .gitignore)
Svelte config The svelte/kit config can live in two places: passed straight to the sveltekit() plugin in vite.config.{js,ts}, or as a default export in a separate svelte.config.{js,ts}. Projects created by sv keep their config inside vite.config.js and ship no svelte.config.js.
svelteConfig lets add-ons read and edit that config wherever it lives - the sveltekit() argument in vite.config.{js,ts}, or a svelte.config.{js,ts} default export - without having to know which.
svelteConfig.edit You address options by name and the helper writes each one to the right place, so you never deal with the kit nesting yourself. Svelte-level options (compilerOptions, preprocess, extensions, vitePlugin) sit on the config object; everything else (adapter, alias, files, typescript, …) is a kit option, which means flattened onto the sveltekit() argument in a vite config, or nested under kit in a svelte.config.
import { svelteConfig ( alias ) const svelteConfig : {
edit : ( target : {
sv : SvFileApi ;
cwd : string ;
}, editFn : SvelteConfEdit ) => void ;
find : ( source : ConfigSource ) => SvelteConfigLocation | null ;
read : ( source : ConfigSource ) => SvelteConfigObjects | null ;
}
import svelteConfig Helpers for the svelte/kit config, which can live either in a svelte.config.{js,ts} default
export or in the object passed to sveltekit() in a vite.config.{js,ts}.
} from '@sveltejs/sv-utils' ;
svelteConfig ( alias ) const svelteConfig : {
edit : ( target : {
sv : SvFileApi ;
cwd : string ;
}, editFn : SvelteConfEdit ) => void ;
find : ( source : ConfigSource ) => SvelteConfigLocation | null ;
read : ( source : ConfigSource ) => SvelteConfigObjects | null ;
}
import svelteConfig Helpers for the svelte/kit config, which can live either in a svelte.config.{js,ts} default
export or in the object passed to sveltekit() in a vite.config.{js,ts}.
. edit ( property ) edit : ( target : {
sv : SvFileApi ;
cwd : string ;
}, editFn : SvelteConfEdit ) => void Edit the config wherever it lives (creating vite.config.js if there is none).
({ sv ( property ) sv : SvFileApi , cwd ( property ) cwd : string }, ({ ast ( parameter ) ast : Program , property ( parameter ) property : < T extends Expression | Identifier > ( name : string , opts : {
fallback : T ;
}) => T Get-or-create a top-level config option's value, placed in the correct location for its name
(kit-level options end up under kit in a svelte.config, flattened in a vite.config).
, override ( parameter ) override : ( props : ObjectMap$1 , opts ? : {
dropLeadingComments ? : string [];
}) => void Set/override top-level config options, each routed to the correct location by its name.
Pass dropLeadingComments with option names whose now-stale leading comments should be removed
(e.g. the adapter-auto note when switching adapters).
, js ( parameter ) js : typeof index_d_exports$3 }) => {
js ( parameter ) js : typeof index_d_exports$3 . array ( alias ) namespace index_d_exports$3 . array
export index_d_exports$3 . array . append ( alias ) array_d_exports . append ( node : ArrayExpression , element : string | Expression | SpreadElement ): void
export array_d_exports . append ( property ( parameter ) property : < ArrayExpression > ( name : string , opts : {
fallback : ArrayExpression ;
}) => ArrayExpression Get-or-create a top-level config option's value, placed in the correct location for its name
(kit-level options end up under kit in a svelte.config, flattened in a vite.config).
( 'extensions' , { fallback ( property ) fallback : ArrayExpression : js ( parameter ) js : typeof index_d_exports$3 . array ( alias ) namespace index_d_exports$3 . array
export index_d_exports$3 . array . create ( alias ) array_d_exports . create (): ArrayExpression
export array_d_exports . create () }), '.svx' );
js ( parameter ) js : typeof index_d_exports$3 . imports ( alias ) namespace index_d_exports$3 . imports
export index_d_exports$3 . imports . addDefault ( alias ) imports_d_exports . addDefault ( node : Program , options : {
from : string ;
as : string ;
}): void
export imports_d_exports . addDefault ( ast ( parameter ) ast : Program , { from ( property ) from : string : '@sveltejs/adapter-node' , as ( property ) as : string : 'adapter' });
override ( parameter ) override : ( props : ObjectMap$1 , opts ? : {
dropLeadingComments ? : string [];
}) => void Set/override top-level config options, each routed to the correct location by its name.
Pass dropLeadingComments with option names whose now-stale leading comments should be removed
(e.g. the adapter-auto note when switching adapters).
({
adapter ( property ) adapter : CallExpression : js ( parameter ) js : typeof index_d_exports$3 . functions ( alias ) namespace index_d_exports$3 . functions
export index_d_exports$3 . functions . createCall ( alias ) function_d_exports . createCall ( options : {
name : string ;
args : Array < string | Expression > ;
useIdentifiers ? : boolean ;
}): CallExpression
export function_d_exports . createCall ({ name ( property ) name : string : 'adapter' , args ( property ) args : ( string | Expression )[] String args become literals (or identifiers with useIdentifiers); expression nodes are passed through as-is.
: [], useIdentifiers ( property ) useIdentifiers ? : boolean | undefined : true })
});
});
property(name, { fallback }) - get-or-create an option’s value to mutate in place (arrays, nested objects).
override(props, { dropLeadingComments }) - set/replace options; dropLeadingComments clears a now-stale leading comment (e.g. the adapter-auto note when switching adapters).
It writes through sv.file, so the edit is tracked like any other. If the project has neither config file, a svelte.config.js is created.
svelteConfig.find / svelteConfig.read Lower-level building blocks, both reading candidate files through an injected read(path) (returns the file contents or null) so detection stays static - the config is never executed:
svelteConfig.find(read) - returns { path, kind } or null (kind is 'vite' or 'svelte'; svelte.config wins when both are present).
svelteConfig.read(read) - locates and parses in one pass, returning { location, config, kit } (the object expressions) or null.
Package manager helpers pnpm.allowBuilds Returns a transform for pnpm-workspace.yaml that adds packages to the pnpm “allow builds” config. Use with sv.file when the project uses pnpm.
cwd is the target project: the pnpm version that would run there (via pnpm --version) decides the shape, so the invoker’s packageManager pin is not used.
pnpm >= 11: writes to the unified allowBuilds map ({ pkg: true }), migrating any legacy onlyBuiltDependencies list into the map.
pnpm < 11: writes to the legacy onlyBuiltDependencies list.
import { pnpm ( alias ) namespace pnpm
import pnpm } from '@sveltejs/sv-utils' ;
if ( packageManager any === 'pnpm' ) {
sv any . file any (
file any . findUp any ( 'pnpm-workspace.yaml' ),
pnpm ( alias ) namespace pnpm
import pnpm . allowBuilds ( alias ) pnpm_d_exports . allowBuilds ( options : {
cwd : string ;
packages : string [];
}): TransformFn
export pnpm_d_exports . allowBuilds Returns a TransformFn for pnpm-workspace.yaml that adds packages to the
pnpm "allow builds" config.
The version of pnpm that would run in cwd decides the shape:
on pnpm >= 11 writes to the unified allowBuilds map ({ pkg: true }),
migrating any legacy onlyBuiltDependencies list into the map;
on pnpm < 11 writes to the legacy onlyBuiltDependencies list;
on pnpm < 10.5 writes nothing (see
{@link
supportsWorkspaceSettings
}
).
if ( packageManager === 'pnpm' ) {
sv . file ( file . findUp ( 'pnpm-workspace.yaml' ), pnpm . allowBuilds ({ cwd , packages : [ 'my-native-dep' ] }));
} ({ cwd ( property ) cwd : string Target project directory, whose pnpm version decides which config shape is written.
, packages ( property ) packages : string [] : [ 'my-native-dep' ] })
);
} Browser usage The package root pulls in Node-only APIs (file system, package manager detection, shell lookups, terminal colors). For browser bundles - in-browser playgrounds, sandboxes, ... - import @sveltejs/sv-utils/browser instead, which exposes the environment-agnostic subset: parse, transforms, the language namespaces (js, svelte, css, html, json, text), Walker, dedent, the version helpers, sanitizeName, minimizeDiff, createPrinter and downloadJson.
import { parse ( alias ) const parse : {
css : ( source : string ) => {
ast : Omit < _CSS . StyleSheetBase , "attributes" | "content" > ;
} & ParseBase ;
html : ( source : string ) => {
ast : AST . Fragment ;
} & ParseBase ;
json : ( source : string ) => {
data : any ;
} & ParseBase ;
script : ( source : string ) => {
ast : Program ;
comments : Comments ;
} & ParseBase ;
svelte : ( source : string ) => {
ast : AST . Root ;
} & ParseBase ;
toml : ( source : string ) => {
data : TomlTable ;
} & ParseBase ;
yaml : ( source : string ) => {
data : YamlDocument ;
} & ParseBase ;
}
import parse Low-level parsers. Prefer transforms for add-on file edits — it picks the
right parser for you and handles generateCode() automatically.
Use parse directly when you need error handling around parsing or
conditional parser selection at runtime.
import { parse } from '@sveltejs/sv-utils' ;
const { ast , generateCode } = parse . script ( 'function add(a, b) { return a + b; }' );
const { ast , generateCode } = parse . svelte ( '<div>Hello, world!</div>' );
const { ast , generateCode } = parse . css ( 'body { color: red; }' );
const { data , generateCode } = parse . json ( '{ "name": "John", "age": 30 }' );
const { data , generateCode } = parse . yaml ( 'name: John' );
const { data , generateCode } = parse . toml ( 'name = "John"' );
const { ast , generateCode } = parse . html ( '<div>Hello, world!</div>' ); , transforms ( alias ) namespace transforms
import transforms } from '@sveltejs/sv-utils/browser' ;