CLIAPI

sv-utils

@sveltejs/sv-utils is an add-on utility for parsing, transforming, and generating code..

npm install -D @sveltejs/sv-utils

transforms

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) const transforms: {
    script(cb: (file: {
        ast: Program;
        comments: Comments;
        content: string;
        js: typeof index_d_exports$3;
    }) => void | false, options?: TransformOptions): TransformFn;
    svelte(cb: (file: {
        ast: AST.Root;
        content: string;
        svelte: typeof index_d_exports$4;
        js: typeof index_d_exports$3;
    }) => void | false, options?: TransformOptions): TransformFn;
    ... 6 more ...;
    text(cb: (file: {
        content: string;
        text: typeof text_d_exports;
    }) => string | false): TransformFn;
}
import transformsFile transform primitives that know their format.
sv-utils = what to do to content, sv = where and when to do it.
Each transform wraps: parse -> callback({ast/data, utils}) -> generateCode().
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.
Transforms are curried: call with the callback to get a (content: string) => string | false
function that plugs directly into sv.file().
import { transforms } from '@sveltejs/sv-utils';

// use with sv.file() - curried form plugs in directly
sv.file(files.viteConfig, transforms.script(({ ast, js }) => {
  js.vite.addPlugin(ast, { code: 'kitRoutes()' });
}));

// standalone usage / testing
const result = transforms.script(({ ast, js }) => {
  js.imports.addDefault(ast, { as: 'foo', from: 'foo' });
})(fileContent); } from '@sveltejs/sv-utils';

transforms(alias) const transforms: {
    script(cb: (file: {
        ast: Program;
        comments: Comments;
        content: string;
        js: typeof index_d_exports$3;
    }) => void | false, options?: TransformOptions): TransformFn;
    svelte(cb: (file: {
        ast: AST.Root;
        content: string;
        svelte: typeof index_d_exports$4;
        js: typeof index_d_exports$3;
    }) => void | false, options?: TransformOptions): TransformFn;
    ... 6 more ...;
    text(cb: (file: {
        content: string;
        text: typeof text_d_exports;
    }) => string | false): TransformFn;
}
import transformsFile transform primitives that know their format.
sv-utils = what to do to content, sv = where and when to do it.
Each transform wraps: parse -> callback({ast/data, utils}) -> generateCode().
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.
Transforms are curried: call with the callback to get a (content: string) => string | false
function that plugs directly into sv.file().
import { transforms } from '@sveltejs/sv-utils';

// use with sv.file() - curried form plugs in directly
sv.file(files.viteConfig, transforms.script(({ ast, js }) => {
  js.vite.addPlugin(ast, { code: 'kitRoutes()' });
}));

// standalone usage / testing
const result = transforms.script(({ ast, js }) => {
  js.imports.addDefault(ast, { as: 'foo', from: 'foo' });
})(fileContent);.script(method) script(cb: (file: {
    ast: Program;
    comments: Comments;
    content: string;
    js: typeof index_d_exports$3;
}) => void | false, options?: TransformOptions): TransformFnTransform a JavaScript/TypeScript file.
Return false from the callback to abort.
(/* ... */);
transforms(alias) const transforms: {
    script(cb: (file: {
        ast: Program;
        comments: Comments;
        content: string;
        js: typeof index_d_exports$3;
    }) => void | false, options?: TransformOptions): TransformFn;
    svelte(cb: (file: {
        ast: AST.Root;
        content: string;
        svelte: typeof index_d_exports$4;
        js: typeof index_d_exports$3;
    }) => void | false, options?: TransformOptions): TransformFn;
    ... 6 more ...;
    text(cb: (file: {
        content: string;
        text: typeof text_d_exports;
    }) => string | false): TransformFn;
}
import transformsFile transform primitives that know their format.
sv-utils = what to do to content, sv = where and when to do it.
Each transform wraps: parse -> callback({ast/data, utils}) -> generateCode().
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.
Transforms are curried: call with the callback to get a (content: string) => string | false
function that plugs directly into sv.file().
import { transforms } from '@sveltejs/sv-utils';

// use with sv.file() - curried form plugs in directly
sv.file(files.viteConfig, transforms.script(({ ast, js }) => {
  js.vite.addPlugin(ast, { code: 'kitRoutes()' });
}));

// standalone usage / testing
const result = transforms.script(({ ast, js }) => {
  js.imports.addDefault(ast, { as: 'foo', from: 'foo' });
})(fileContent);.svelte(method) svelte(cb: (file: {
    ast: AST.Root;
    content: string;
    svelte: typeof index_d_exports$4;
    js: typeof index_d_exports$3;
}) => void | false, options?: TransformOptions): TransformFnTransform a Svelte component file.
Return false from the callback to abort.
(/* ... */);
// ...

transforms.script

Transform a JavaScript/TypeScript file. The callback receives { ast, comments, content, js }.

import { transforms(alias) const transforms: {
    script(cb: (file: {
        ast: Program;
        comments: Comments;
        content: string;
        js: typeof index_d_exports$3;
    }) => void | false, options?: TransformOptions): TransformFn;
    svelte(cb: (file: {
        ast: AST.Root;
        content: string;
        svelte: typeof index_d_exports$4;
        js: typeof index_d_exports$3;
    }) => void | false, options?: TransformOptions): TransformFn;
    ... 6 more ...;
    text(cb: (file: {
        content: string;
        text: typeof text_d_exports;
    }) => string | false): TransformFn;
}
import transformsFile transform primitives that know their format.
sv-utils = what to do to content, sv = where and when to do it.
Each transform wraps: parse -> callback({ast/data, utils}) -> generateCode().
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.
Transforms are curried: call with the callback to get a (content: string) => string | false
function that plugs directly into sv.file().
import { transforms } from '@sveltejs/sv-utils';

// use with sv.file() - curried form plugs in directly
sv.file(files.viteConfig, transforms.script(({ ast, js }) => {
  js.vite.addPlugin(ast, { code: 'kitRoutes()' });
}));

// standalone usage / testing
const result = transforms.script(({ ast, js }) => {
  js.imports.addDefault(ast, { as: 'foo', from: 'foo' });
})(fileContent); } from '@sveltejs/sv-utils';

svany.fileany(
	fileany.viteConfigany,
	transforms(alias) const transforms: {
    script(cb: (file: {
        ast: Program;
        comments: Comments;
        content: string;
        js: typeof index_d_exports$3;
    }) => void | false, options?: TransformOptions): TransformFn;
    svelte(cb: (file: {
        ast: AST.Root;
        content: string;
        svelte: typeof index_d_exports$4;
        js: typeof index_d_exports$3;
    }) => void | false, options?: TransformOptions): TransformFn;
    ... 6 more ...;
    text(cb: (file: {
        content: string;
        text: typeof text_d_exports;
    }) => string | false): TransformFn;
}
import transformsFile transform primitives that know their format.
sv-utils = what to do to content, sv = where and when to do it.
Each transform wraps: parse -> callback({ast/data, utils}) -> generateCode().
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.
Transforms are curried: call with the callback to get a (content: string) => string | false
function that plugs directly into sv.file().
import { transforms } from '@sveltejs/sv-utils';

// use with sv.file() - curried form plugs in directly
sv.file(files.viteConfig, transforms.script(({ ast, js }) => {
  js.vite.addPlugin(ast, { code: 'kitRoutes()' });
}));

// standalone usage / testing
const result = transforms.script(({ ast, js }) => {
  js.imports.addDefault(ast, { as: 'foo', from: 'foo' });
})(fileContent);.script(method) script(cb: (file: {
    ast: Program;
    comments: Comments;
    content: string;
    js: typeof index_d_exports$3;
}) => void | false, options?: TransformOptions): TransformFnTransform 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()' });
	})
);

transforms.svelte

Transform a Svelte component. The callback receives { ast, content, svelte, js }.

import { transforms(alias) const transforms: {
    script(cb: (file: {
        ast: Program;
        comments: Comments;
        content: string;
        js: typeof index_d_exports$3;
    }) => void | false, options?: TransformOptions): TransformFn;
    svelte(cb: (file: {
        ast: AST.Root;
        content: string;
        svelte: typeof index_d_exports$4;
        js: typeof index_d_exports$3;
    }) => void | false, options?: TransformOptions): TransformFn;
    ... 6 more ...;
    text(cb: (file: {
        content: string;
        text: typeof text_d_exports;
    }) => string | false): TransformFn;
}
import transformsFile transform primitives that know their format.
sv-utils = what to do to content, sv = where and when to do it.
Each transform wraps: parse -> callback({ast/data, utils}) -> generateCode().
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.
Transforms are curried: call with the callback to get a (content: string) => string | false
function that plugs directly into sv.file().
import { transforms } from '@sveltejs/sv-utils';

// use with sv.file() - curried form plugs in directly
sv.file(files.viteConfig, transforms.script(({ ast, js }) => {
  js.vite.addPlugin(ast, { code: 'kitRoutes()' });
}));

// standalone usage / testing
const result = transforms.script(({ ast, js }) => {
  js.imports.addDefault(ast, { as: 'foo', from: 'foo' });
})(fileContent); } from '@sveltejs/sv-utils';

svany.fileany(
	layoutPathany,
	transforms(alias) const transforms: {
    script(cb: (file: {
        ast: Program;
        comments: Comments;
        content: string;
        js: typeof index_d_exports$3;
    }) => void | false, options?: TransformOptions): TransformFn;
    svelte(cb: (file: {
        ast: AST.Root;
        content: string;
        svelte: typeof index_d_exports$4;
        js: typeof index_d_exports$3;
    }) => void | false, options?: TransformOptions): TransformFn;
    ... 6 more ...;
    text(cb: (file: {
        content: string;
        text: typeof text_d_exports;
    }) => string | false): TransformFn;
}
import transformsFile transform primitives that know their format.
sv-utils = what to do to content, sv = where and when to do it.
Each transform wraps: parse -> callback({ast/data, utils}) -> generateCode().
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.
Transforms are curried: call with the callback to get a (content: string) => string | false
function that plugs directly into sv.file().
import { transforms } from '@sveltejs/sv-utils';

// use with sv.file() - curried form plugs in directly
sv.file(files.viteConfig, transforms.script(({ ast, js }) => {
  js.vite.addPlugin(ast, { code: 'kitRoutes()' });
}));

// standalone usage / testing
const result = transforms.script(({ ast, js }) => {
  js.imports.addDefault(ast, { as: 'foo', from: 'foo' });
})(fileContent);.svelte(method) svelte(cb: (file: {
    ast: AST.Root;
    content: string;
    svelte: typeof index_d_exports$4;
    js: typeof index_d_exports$3;
}) => void | false, options?: TransformOptions): TransformFnTransform 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 />');
	})
);

transforms.svelteScript

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) const transforms: {
    script(cb: (file: {
        ast: Program;
        comments: Comments;
        content: string;
        js: typeof index_d_exports$3;
    }) => void | false, options?: TransformOptions): TransformFn;
    svelte(cb: (file: {
        ast: AST.Root;
        content: string;
        svelte: typeof index_d_exports$4;
        js: typeof index_d_exports$3;
    }) => void | false, options?: TransformOptions): TransformFn;
    ... 6 more ...;
    text(cb: (file: {
        content: string;
        text: typeof text_d_exports;
    }) => string | false): TransformFn;
}
import transformsFile transform primitives that know their format.
sv-utils = what to do to content, sv = where and when to do it.
Each transform wraps: parse -> callback({ast/data, utils}) -> generateCode().
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.
Transforms are curried: call with the callback to get a (content: string) => string | false
function that plugs directly into sv.file().
import { transforms } from '@sveltejs/sv-utils';

// use with sv.file() - curried form plugs in directly
sv.file(files.viteConfig, transforms.script(({ ast, js }) => {
  js.vite.addPlugin(ast, { code: 'kitRoutes()' });
}));

// standalone usage / testing
const result = transforms.script(({ ast, js }) => {
  js.imports.addDefault(ast, { as: 'foo', from: 'foo' });
})(fileContent); } from '@sveltejs/sv-utils';

svany.fileany(
	layoutPathany,
	transforms(alias) const transforms: {
    script(cb: (file: {
        ast: Program;
        comments: Comments;
        content: string;
        js: typeof index_d_exports$3;
    }) => void | false, options?: TransformOptions): TransformFn;
    svelte(cb: (file: {
        ast: AST.Root;
        content: string;
        svelte: typeof index_d_exports$4;
        js: typeof index_d_exports$3;
    }) => void | false, options?: TransformOptions): TransformFn;
    ... 6 more ...;
    text(cb: (file: {
        content: string;
        text: typeof text_d_exports;
    }) => string | false): TransformFn;
}
import transformsFile transform primitives that know their format.
sv-utils = what to do to content, sv = where and when to do it.
Each transform wraps: parse -> callback({ast/data, utils}) -> generateCode().
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.
Transforms are curried: call with the callback to get a (content: string) => string | false
function that plugs directly into sv.file().
import { transforms } from '@sveltejs/sv-utils';

// use with sv.file() - curried form plugs in directly
sv.file(files.viteConfig, transforms.script(({ ast, js }) => {
  js.vite.addPlugin(ast, { code: 'kitRoutes()' });
}));

// standalone usage / testing
const result = transforms.script(({ ast, js }) => {
  js.imports.addDefault(ast, { as: 'foo', from: 'foo' });
})(fileContent);.svelteScript(method) 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): TransformFnTransform 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.ScriptThe 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 />');
	})
);

transforms.css

Transform a CSS file. The callback receives { ast, content, css }.

import { transforms(alias) const transforms: {
    script(cb: (file: {
        ast: Program;
        comments: Comments;
        content: string;
        js: typeof index_d_exports$3;
    }) => void | false, options?: TransformOptions): TransformFn;
    svelte(cb: (file: {
        ast: AST.Root;
        content: string;
        svelte: typeof index_d_exports$4;
        js: typeof index_d_exports$3;
    }) => void | false, options?: TransformOptions): TransformFn;
    ... 6 more ...;
    text(cb: (file: {
        content: string;
        text: typeof text_d_exports;
    }) => string | false): TransformFn;
}
import transformsFile transform primitives that know their format.
sv-utils = what to do to content, sv = where and when to do it.
Each transform wraps: parse -> callback({ast/data, utils}) -> generateCode().
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.
Transforms are curried: call with the callback to get a (content: string) => string | false
function that plugs directly into sv.file().
import { transforms } from '@sveltejs/sv-utils';

// use with sv.file() - curried form plugs in directly
sv.file(files.viteConfig, transforms.script(({ ast, js }) => {
  js.vite.addPlugin(ast, { code: 'kitRoutes()' });
}));

// standalone usage / testing
const result = transforms.script(({ ast, js }) => {
  js.imports.addDefault(ast, { as: 'foo', from: 'foo' });
})(fileContent); } from '@sveltejs/sv-utils';

svany.fileany(
	fileany.stylesheetany,
	transforms(alias) const transforms: {
    script(cb: (file: {
        ast: Program;
        comments: Comments;
        content: string;
        js: typeof index_d_exports$3;
    }) => void | false, options?: TransformOptions): TransformFn;
    svelte(cb: (file: {
        ast: AST.Root;
        content: string;
        svelte: typeof index_d_exports$4;
        js: typeof index_d_exports$3;
    }) => void | false, options?: TransformOptions): TransformFn;
    ... 6 more ...;
    text(cb: (file: {
        content: string;
        text: typeof text_d_exports;
    }) => string | false): TransformFn;
}
import transformsFile transform primitives that know their format.
sv-utils = what to do to content, sv = where and when to do it.
Each transform wraps: parse -> callback({ast/data, utils}) -> generateCode().
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.
Transforms are curried: call with the callback to get a (content: string) => string | false
function that plugs directly into sv.file().
import { transforms } from '@sveltejs/sv-utils';

// use with sv.file() - curried form plugs in directly
sv.file(files.viteConfig, transforms.script(({ ast, js }) => {
  js.vite.addPlugin(ast, { code: 'kitRoutes()' });
}));

// standalone usage / testing
const result = transforms.script(({ ast, js }) => {
  js.imports.addDefault(ast, { as: 'foo', from: 'foo' });
})(fileContent);.css(method) css(cb: (file: {
    ast: Omit<_CSS.StyleSheetBase, "attributes" | "content">;
    content: string;
    css: typeof index_d_exports$1;
}) => void | false, options?: TransformOptions): TransformFnTransform 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'" });
	})
);

transforms.json

Transform a JSON file. Mutate the data object directly. The callback receives { data, content, json }.

import { transforms(alias) const transforms: {
    script(cb: (file: {
        ast: Program;
        comments: Comments;
        content: string;
        js: typeof index_d_exports$3;
    }) => void | false, options?: TransformOptions): TransformFn;
    svelte(cb: (file: {
        ast: AST.Root;
        content: string;
        svelte: typeof index_d_exports$4;
        js: typeof index_d_exports$3;
    }) => void | false, options?: TransformOptions): TransformFn;
    ... 6 more ...;
    text(cb: (file: {
        content: string;
        text: typeof text_d_exports;
    }) => string | false): TransformFn;
}
import transformsFile transform primitives that know their format.
sv-utils = what to do to content, sv = where and when to do it.
Each transform wraps: parse -> callback({ast/data, utils}) -> generateCode().
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.
Transforms are curried: call with the callback to get a (content: string) => string | false
function that plugs directly into sv.file().
import { transforms } from '@sveltejs/sv-utils';

// use with sv.file() - curried form plugs in directly
sv.file(files.viteConfig, transforms.script(({ ast, js }) => {
  js.vite.addPlugin(ast, { code: 'kitRoutes()' });
}));

// standalone usage / testing
const result = transforms.script(({ ast, js }) => {
  js.imports.addDefault(ast, { as: 'foo', from: 'foo' });
})(fileContent); } from '@sveltejs/sv-utils';

svany.fileany(
	fileany.typeConfigany,
	transforms(alias) const transforms: {
    script(cb: (file: {
        ast: Program;
        comments: Comments;
        content: string;
        js: typeof index_d_exports$3;
    }) => void | false, options?: TransformOptions): TransformFn;
    svelte(cb: (file: {
        ast: AST.Root;
        content: string;
        svelte: typeof index_d_exports$4;
        js: typeof index_d_exports$3;
    }) => void | false, options?: TransformOptions): TransformFn;
    ... 6 more ...;
    text(cb: (file: {
        content: string;
        text: typeof text_d_exports;
    }) => string | false): TransformFn;
}
import transformsFile transform primitives that know their format.
sv-utils = what to do to content, sv = where and when to do it.
Each transform wraps: parse -> callback({ast/data, utils}) -> generateCode().
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.
Transforms are curried: call with the callback to get a (content: string) => string | false
function that plugs directly into sv.file().
import { transforms } from '@sveltejs/sv-utils';

// use with sv.file() - curried form plugs in directly
sv.file(files.viteConfig, transforms.script(({ ast, js }) => {
  js.vite.addPlugin(ast, { code: 'kitRoutes()' });
}));

// standalone usage / testing
const result = transforms.script(({ ast, js }) => {
  js.imports.addDefault(ast, { as: 'foo', from: 'foo' });
})(fileContent);.json(method) json<any>(cb: (file: {
    data: any;
    content: string;
    json: typeof json_d_exports;
}) => void | false, options?: TransformOptions): TransformFnTransform a JSON file.
Return false from the callback to abort.
(({ data(parameter) data: any }) => {
		data(parameter) data: any.compilerOptionsany ??= {};
		data(parameter) data: any.compilerOptionsany.strictany = true;
	})
);

transforms.yaml / transforms.toml

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) const transforms: {
    script(cb: (file: {
        ast: Program;
        comments: Comments;
        content: string;
        js: typeof index_d_exports$3;
    }) => void | false, options?: TransformOptions): TransformFn;
    svelte(cb: (file: {
        ast: AST.Root;
        content: string;
        svelte: typeof index_d_exports$4;
        js: typeof index_d_exports$3;
    }) => void | false, options?: TransformOptions): TransformFn;
    ... 6 more ...;
    text(cb: (file: {
        content: string;
        text: typeof text_d_exports;
    }) => string | false): TransformFn;
}
import transformsFile transform primitives that know their format.
sv-utils = what to do to content, sv = where and when to do it.
Each transform wraps: parse -> callback({ast/data, utils}) -> generateCode().
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.
Transforms are curried: call with the callback to get a (content: string) => string | false
function that plugs directly into sv.file().
import { transforms } from '@sveltejs/sv-utils';

// use with sv.file() - curried form plugs in directly
sv.file(files.viteConfig, transforms.script(({ ast, js }) => {
  js.vite.addPlugin(ast, { code: 'kitRoutes()' });
}));

// standalone usage / testing
const result = transforms.script(({ ast, js }) => {
  js.imports.addDefault(ast, { as: 'foo', from: 'foo' });
})(fileContent); } from '@sveltejs/sv-utils';

svany.fileany(
	'.env',
	transforms(alias) const transforms: {
    script(cb: (file: {
        ast: Program;
        comments: Comments;
        content: string;
        js: typeof index_d_exports$3;
    }) => void | false, options?: TransformOptions): TransformFn;
    svelte(cb: (file: {
        ast: AST.Root;
        content: string;
        svelte: typeof index_d_exports$4;
        js: typeof index_d_exports$3;
    }) => void | false, options?: TransformOptions): TransformFn;
    ... 6 more ...;
    text(cb: (file: {
        content: string;
        text: typeof text_d_exports;
    }) => string | false): TransformFn;
}
import transformsFile transform primitives that know their format.
sv-utils = what to do to content, sv = where and when to do it.
Each transform wraps: parse -> callback({ast/data, utils}) -> generateCode().
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.
Transforms are curried: call with the callback to get a (content: string) => string | false
function that plugs directly into sv.file().
import { transforms } from '@sveltejs/sv-utils';

// use with sv.file() - curried form plugs in directly
sv.file(files.viteConfig, transforms.script(({ ast, js }) => {
  js.vite.addPlugin(ast, { code: 'kitRoutes()' });
}));

// standalone usage / testing
const result = transforms.script(({ ast, js }) => {
  js.imports.addDefault(ast, { as: 'foo', from: 'foo' });
})(fileContent);.text(method) text(cb: (file: {
    content: string;
    text: typeof text_d_exports;
}) => string | false): TransformFnTransform 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 + '\nDATABASE_URL="file:local.db"';
	})
);

Aborting a transform

Return false from any transform callback to abort - the original content is returned unchanged.

import { transforms(alias) const transforms: {
    script(cb: (file: {
        ast: Program;
        comments: Comments;
        content: string;
        js: typeof index_d_exports$3;
    }) => void | false, options?: TransformOptions): TransformFn;
    svelte(cb: (file: {
        ast: AST.Root;
        content: string;
        svelte: typeof index_d_exports$4;
        js: typeof index_d_exports$3;
    }) => void | false, options?: TransformOptions): TransformFn;
    ... 6 more ...;
    text(cb: (file: {
        content: string;
        text: typeof text_d_exports;
    }) => string | false): TransformFn;
}
import transformsFile transform primitives that know their format.
sv-utils = what to do to content, sv = where and when to do it.
Each transform wraps: parse -> callback({ast/data, utils}) -> generateCode().
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.
Transforms are curried: call with the callback to get a (content: string) => string | false
function that plugs directly into sv.file().
import { transforms } from '@sveltejs/sv-utils';

// use with sv.file() - curried form plugs in directly
sv.file(files.viteConfig, transforms.script(({ ast, js }) => {
  js.vite.addPlugin(ast, { code: 'kitRoutes()' });
}));

// standalone usage / testing
const result = transforms.script(({ ast, js }) => {
  js.imports.addDefault(ast, { as: 'foo', from: 'foo' });
})(fileContent); } from '@sveltejs/sv-utils';

svany.fileany(
	'eslint.config.js',
	transforms(alias) const transforms: {
    script(cb: (file: {
        ast: Program;
        comments: Comments;
        content: string;
        js: typeof index_d_exports$3;
    }) => void | false, options?: TransformOptions): TransformFn;
    svelte(cb: (file: {
        ast: AST.Root;
        content: string;
        svelte: typeof index_d_exports$4;
        js: typeof index_d_exports$3;
    }) => void | false, options?: TransformOptions): TransformFn;
    ... 6 more ...;
    text(cb: (file: {
        content: string;
        text: typeof text_d_exports;
    }) => string | false): TransformFn;
}
import transformsFile transform primitives that know their format.
sv-utils = what to do to content, sv = where and when to do it.
Each transform wraps: parse -> callback({ast/data, utils}) -> generateCode().
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.
Transforms are curried: call with the callback to get a (content: string) => string | false
function that plugs directly into sv.file().
import { transforms } from '@sveltejs/sv-utils';

// use with sv.file() - curried form plugs in directly
sv.file(files.viteConfig, transforms.script(({ ast, js }) => {
  js.vite.addPlugin(ast, { code: 'kitRoutes()' });
}));

// standalone usage / testing
const result = transforms.script(({ ast, js }) => {
  js.imports.addDefault(ast, { as: 'foo', from: 'foo' });
})(fileContent);.script(method) script(cb: (file: {
    ast: Program;
    comments: Comments;
    content: string;
    js: typeof index_d_exports$3;
}) => void | false, options?: TransformOptions): TransformFnTransform 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: existingconst 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: myConfigany });
		if (existingconst existing: any !== myConfigany) {
			// config already exists, don't touch it
			return false;
		}
		// ... continue modifying ast
	})
);

Standalone usage & testing

Transforms are curried functions - call them with the callback, then apply to content:

import { transforms(alias) const transforms: {
    script(cb: (file: {
        ast: Program;
        comments: Comments;
        content: string;
        js: typeof index_d_exports$3;
    }) => void | false, options?: TransformOptions): TransformFn;
    svelte(cb: (file: {
        ast: AST.Root;
        content: string;
        svelte: typeof index_d_exports$4;
        js: typeof index_d_exports$3;
    }) => void | false, options?: TransformOptions): TransformFn;
    ... 6 more ...;
    text(cb: (file: {
        content: string;
        text: typeof text_d_exports;
    }) => string | false): TransformFn;
}
import transformsFile transform primitives that know their format.
sv-utils = what to do to content, sv = where and when to do it.
Each transform wraps: parse -> callback({ast/data, utils}) -> generateCode().
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.
Transforms are curried: call with the callback to get a (content: string) => string | false
function that plugs directly into sv.file().
import { transforms } from '@sveltejs/sv-utils';

// use with sv.file() - curried form plugs in directly
sv.file(files.viteConfig, transforms.script(({ ast, js }) => {
  js.vite.addPlugin(ast, { code: 'kitRoutes()' });
}));

// standalone usage / testing
const result = transforms.script(({ ast, js }) => {
  js.imports.addDefault(ast, { as: 'foo', from: 'foo' });
})(fileContent); } from '@sveltejs/sv-utils';

const transformconst transform: TransformFn = transforms(alias) const transforms: {
    script(cb: (file: {
        ast: Program;
        comments: Comments;
        content: string;
        js: typeof index_d_exports$3;
    }) => void | false, options?: TransformOptions): TransformFn;
    svelte(cb: (file: {
        ast: AST.Root;
        content: string;
        svelte: typeof index_d_exports$4;
        js: typeof index_d_exports$3;
    }) => void | false, options?: TransformOptions): TransformFn;
    ... 6 more ...;
    text(cb: (file: {
        content: string;
        text: typeof text_d_exports;
    }) => string | false): TransformFn;
}
import transformsFile transform primitives that know their format.
sv-utils = what to do to content, sv = where and when to do it.
Each transform wraps: parse -> callback({ast/data, utils}) -> generateCode().
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.
Transforms are curried: call with the callback to get a (content: string) => string | false
function that plugs directly into sv.file().
import { transforms } from '@sveltejs/sv-utils';

// use with sv.file() - curried form plugs in directly
sv.file(files.viteConfig, transforms.script(({ ast, js }) => {
  js.vite.addPlugin(ast, { code: 'kitRoutes()' });
}));

// standalone usage / testing
const result = transforms.script(({ ast, js }) => {
  js.imports.addDefault(ast, { as: 'foo', from: 'foo' });
})(fileContent);.script(method) script(cb: (file: {
    ast: Program;
    comments: Comments;
    content: string;
    js: typeof index_d_exports$3;
}) => void | false, options?: TransformOptions): TransformFnTransform 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 resultconst result: string | false = transformconst transform: (content: string) => string | false('export default {}');

Composability

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:

svany.fileany(pathany, (content(parameter) content: any) => {
	// curried
	const transformconst transform: any = transformsany.scriptany(({ ast(parameter) ast: any, js(parameter) js: any }) => {
		js(parameter) js: any.importsany.addDefaultany(ast(parameter) ast: any, { as(property) as: string: 'foo', from(property) from: string: 'bar' });
	});

	// parser manipulation
	content(parameter) content: any = transformconst transform: any(content(parameter) content: any);

	// raw string manipulation
	content(parameter) content: any = content(parameter) content: any.replaceany('foo', 'baz');

	return content(parameter) content: any;
});

Add-ons can also export reusable transform functions:

import { transforms(alias) const transforms: {
    script(cb: (file: {
        ast: Program;
        comments: Comments;
        content: string;
        js: typeof index_d_exports$3;
    }) => void | false, options?: TransformOptions): TransformFn;
    svelte(cb: (file: {
        ast: AST.Root;
        content: string;
        svelte: typeof index_d_exports$4;
        js: typeof index_d_exports$3;
    }) => void | false, options?: TransformOptions): TransformFn;
    ... 6 more ...;
    text(cb: (file: {
        content: string;
        text: typeof text_d_exports;
    }) => string | false): TransformFn;
}
import transformsFile transform primitives that know their format.
sv-utils = what to do to content, sv = where and when to do it.
Each transform wraps: parse -> callback({ast/data, utils}) -> generateCode().
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.
Transforms are curried: call with the callback to get a (content: string) => string | false
function that plugs directly into sv.file().
import { transforms } from '@sveltejs/sv-utils';

// use with sv.file() - curried form plugs in directly
sv.file(files.viteConfig, transforms.script(({ ast, js }) => {
  js.vite.addPlugin(ast, { code: 'kitRoutes()' });
}));

// standalone usage / testing
const result = transforms.script(({ ast, js }) => {
  js.imports.addDefault(ast, { as: 'foo', from: 'foo' });
})(fileContent); } from '@sveltejs/sv-utils';

// reusable - export from your package
export const addFooImportconst addFooImport: TransformFn = transforms(alias) const transforms: {
    script(cb: (file: {
        ast: Program;
        comments: Comments;
        content: string;
        js: typeof index_d_exports$3;
    }) => void | false, options?: TransformOptions): TransformFn;
    svelte(cb: (file: {
        ast: AST.Root;
        content: string;
        svelte: typeof index_d_exports$4;
        js: typeof index_d_exports$3;
    }) => void | false, options?: TransformOptions): TransformFn;
    ... 6 more ...;
    text(cb: (file: {
        content: string;
        text: typeof text_d_exports;
    }) => string | false): TransformFn;
}
import transformsFile transform primitives that know their format.
sv-utils = what to do to content, sv = where and when to do it.
Each transform wraps: parse -> callback({ast/data, utils}) -> generateCode().
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.
Transforms are curried: call with the callback to get a (content: string) => string | false
function that plugs directly into sv.file().
import { transforms } from '@sveltejs/sv-utils';

// use with sv.file() - curried form plugs in directly
sv.file(files.viteConfig, transforms.script(({ ast, js }) => {
  js.vite.addPlugin(ast, { code: 'kitRoutes()' });
}));

// standalone usage / testing
const result = transforms.script(({ ast, js }) => {
  js.imports.addDefault(ast, { as: 'foo', from: 'foo' });
})(fileContent);.svelte(method) svelte(cb: (file: {
    ast: AST.Root;
    content: string;
    svelte: typeof index_d_exports$4;
    js: typeof index_d_exports$3;
}) => void | false, options?: TransformOptions): TransformFnTransform 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 | nullThe parsed <script> element, if exists
.content(property) AST.Script.content: Program, { as(property) as: string: 'Foo', from(property) from: string: './Foo.svelte' });
});

svany.fileany('+page.svelte', addFooImportany);
svany.fileany('index.svelte', addFooImportany);

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 parseLow-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 { astconst ast: Program, generateCodeconst generateCode: () => stringGenerate 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 parseLow-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(contentany);
const { astconst ast: AST.Root, generateCodeconst generateCode: () => stringGenerate 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 parseLow-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(contentany);
const { astconst ast: Omit<_CSS.StyleSheetBase, "attributes" | "content">, generateCodeconst generateCode: () => stringGenerate 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 parseLow-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(contentany);
const { dataconst data: any, generateCodeconst generateCode: () => stringGenerate 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 parseLow-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(contentany);
const { dataconst data: YamlDocument, generateCodeconst generateCode: () => stringGenerate 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 parseLow-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(contentany);
const { dataconst data: TomlTable, generateCodeconst generateCode: () => stringGenerate 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 parseLow-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(contentany);
const { astconst ast: AST.Fragment, generateCodeconst generateCode: () => stringGenerate 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 parseLow-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(contentany);

Language tooling

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 svelteConfigHelpers 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';

// inside an add-on's `run({ sv, cwd })`:
svelteConfig(alias) const svelteConfig: {
    edit: (target: {
        sv: SvFileApi;
        cwd: string;
    }, editFn: SvelteConfEdit) => void;
    find: (source: ConfigSource) => SvelteConfigLocation | null;
    read: (source: ConfigSource) => SvelteConfigObjects | null;
}
import svelteConfigHelpers 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) => voidEdit 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;
}) => TGet-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[];
}) => voidSet/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 }) => {
	// svelte-level option - get-or-create its value, then mutate in place:
	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;
}) => ArrayExpressionGet-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');

	// kit option - routed automatically, no `kit` nesting to think about:
	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[];
}) => voidSet/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 (packageManagerany === 'pnpm') {
	svany.fileany(
		fileany.findUpany('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.allowBuildsReturns 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.

if (packageManager === 'pnpm') {
  sv.file(file.findUp('pnpm-workspace.yaml'), pnpm.allowBuilds({ cwd, packages: ['my-native-dep'] }));
}({ cwd(property) cwd: stringTarget project directory, whose pnpm version decides which config shape is written.
, packages(property) packages: string[]: ['my-native-dep'] })
	);
}

Demo pages

defineDemoPage

Wires an add-on demo into a SvelteKit project. Every demo is listed in a floating DemoLinks post-it rendered from the root layout, whatever the template. It returns the pieces you spread into sv.file():

import { defineDemoPage(alias) function defineDemoPage(name: string, language: "ts" | "js", kitRoutes: string): DemoPage
import defineDemoPageWires an add-on demo into a SvelteKit project: a floating DemoLinks post-it,
rendered from the root layout, listing every add-on demo route.
const demo = defineDemoPage('my-addon', language, directory.kitRoutes);
sv.file(...demo.links);
sv.file(...demo.layout);
sv.file(`${demo.addonPath}/+page.svelte`, ...);
Both transforms are idempotent, so re-running an add-on won't duplicate entries.
 } from '@sveltejs/sv-utils';

const democonst demo: DemoPage = defineDemoPage(alias) defineDemoPage(name: string, language: "ts" | "js", kitRoutes: string): DemoPage
import defineDemoPageWires an add-on demo into a SvelteKit project: a floating DemoLinks post-it,
rendered from the root layout, listing every add-on demo route.
const demo = defineDemoPage('my-addon', language, directory.kitRoutes);
sv.file(...demo.links);
sv.file(...demo.layout);
sv.file(`${demo.addonPath}/+page.svelte`, ...);
Both transforms are idempotent, so re-running an add-on won't duplicate entries.
('my-addon', languageany, directoryany.kitRoutesany);

svany.fileany(...democonst demo: DemoPage.links(property) links: [path: `${KitRoutes}/demo/DemoLinks.svelte`, transform: TransformFn]Upserts the add-on link into the floating DemoLinks component.
); // adds `/demo/my-addon` to `<routes>/demo/DemoLinks.svelte`
svany.fileany(...democonst demo: DemoPage.layout(property) layout: [path: `${KitRoutes}/+layout.svelte`, transform: TransformFn]Upserts <DemoLinks /> into the root layout.
); // renders `<DemoLinks />` in `<routes>/+layout.svelte`
svany.fileany(`${democonst demo: DemoPage.addonPath(property) addonPath: `${KitRoutes}/demo/${AddonName}`Where the add-on's own demo route belongs.
}/+page.svelte` /* your demo route */);

addonPath - <routes>/demo/<name>, where your own demo route belongs.
links - a [path, transform] pair for <routes>/demo/DemoLinks.svelte (created if missing).
layout - a [path, transform] pair for <routes>/+layout.svelte (created if missing).

Both transforms are idempotent, so re-running an add-on won’t duplicate entries. Only call them when the user asked for a demo (e.g. a demo option), so projects without demos don’t get the post-it. To opt out, delete DemoLinks.svelte and its usage in the layout.

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 parseLow-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) const transforms: {
    script(cb: (file: {
        ast: Program;
        comments: Comments;
        content: string;
        js: typeof index_d_exports$3;
    }) => void | false, options?: TransformOptions): TransformFn;
    svelte(cb: (file: {
        ast: AST.Root;
        content: string;
        svelte: typeof index_d_exports$4;
        js: typeof index_d_exports$3;
    }) => void | false, options?: TransformOptions): TransformFn;
    ... 6 more ...;
    text(cb: (file: {
        content: string;
        text: typeof text_d_exports;
    }) => string | false): TransformFn;
}
import transformsFile transform primitives that know their format.
sv-utils = what to do to content, sv = where and when to do it.
Each transform wraps: parse -> callback({ast/data, utils}) -> generateCode().
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.
Transforms are curried: call with the callback to get a (content: string) => string | false
function that plugs directly into sv.file().
import { transforms } from '@sveltejs/sv-utils';

// use with sv.file() - curried form plugs in directly
sv.file(files.viteConfig, transforms.script(({ ast, js }) => {
  js.vite.addPlugin(ast, { code: 'kitRoutes()' });
}));

// standalone usage / testing
const result = transforms.script(({ ast, js }) => {
  js.imports.addDefault(ast, { as: 'foo', from: 'foo' });
})(fileContent); } from '@sveltejs/sv-utils/browser';

Edit this page on GitHub llms.txt

previous next