CLIAPI

sv-utils

@sveltejs/sv-utils is currently experimental. The API may change. Full documentation is not yet available.

@sveltejs/sv-utils is an add-on utilty 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 { import transformstransforms } from '@sveltejs/sv-utils';

import transformstransforms.script(/* ... */);
import transformstransforms.svelte(/* ... */);
// ...

transforms.script

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

import { import transformstransforms } from '@sveltejs/sv-utils';

sv.file(
	files.viteConfig,
	import transformstransforms.script(({ ast: anyast, js: anyjs }) => {
		js: anyjs.imports.addDefault(ast: anyast, { as: stringas: 'foo', from: stringfrom: 'foo' });
		js: anyjs.vite.addPlugin(ast: anyast, { code: stringcode: 'foo()' });
	})
);

transforms.svelte

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

import { import transformstransforms } from '@sveltejs/sv-utils';

sv.file(
	layoutPath,
	import transformstransforms.svelte(({ ast: anyast, svelte: anysvelte }) => {
		svelte: anysvelte.addFragment(ast: anyast, '<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 { import transformstransforms } from '@sveltejs/sv-utils';

sv.file(
	layoutPath,
	import transformstransforms.svelteScript({ language: stringlanguage: 'ts' }, ({ ast: anyast, svelte: anysvelte, js: anyjs }) => {
		js: anyjs.imports.addDefault(ast: anyast.instance.content, { as: stringas: 'Foo', from: stringfrom: './Foo.svelte' });
		svelte: anysvelte.addFragment(ast: anyast, '<Foo />');
	})
);

transforms.css

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

import { import transformstransforms } from '@sveltejs/sv-utils';

sv.file(
	files.stylesheet,
	import transformstransforms.css(({ ast: anyast, css: anycss }) => {
		css: anycss.addAtRule(ast: anyast, { name: stringname: 'import', params: stringparams: "'tailwindcss'" });
	})
);

transforms.json

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

import { import transformstransforms } from '@sveltejs/sv-utils';

sv.file(
	files.tsconfig,
	import transformstransforms.json(({ data: anydata }) => {
		data: anydata.compilerOptions ??= {};
		data: anydata.compilerOptions.strict = 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 { import transformstransforms } from '@sveltejs/sv-utils';

sv.file(
	'.env',
	import transformstransforms.text(({ content: anycontent }) => {
		return content: anycontent + '\nDATABASE_URL="file:local.db"';
	})
);

Aborting a transform

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

import { import transformstransforms } from '@sveltejs/sv-utils';

sv.file(
	files.eslintConfig,
	import transformstransforms.script(({ ast: anyast, js: anyjs }) => {
		const { value: const existing: anyexisting } = js: anyjs.exports.createDefault(ast: anyast, { fallback: anyfallback: myConfig });
		if (const existing: anyexisting !== myConfig) {
			// 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 { import transformstransforms } from '@sveltejs/sv-utils';

const const transform: anytransform = import transformstransforms.script(({ ast: anyast, js: anyjs }) => {
	js: anyjs.imports.addDefault(ast: anyast, { as: stringas: 'foo', from: stringfrom: 'foo' });
});
const const result: anyresult = const transform: anytransform('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:

sv.file(path, (content: anycontent) => {
	// curried
	const const transform: anytransform = transforms.script(({ ast: anyast, js: anyjs }) => {
		js: anyjs.imports.addDefault(ast: anyast, { as: stringas: 'foo', from: stringfrom: 'bar' });
	});

	// parser manipulation
	content: anycontent = const transform: anytransform(content: anycontent);

	// raw string manipulation
	content: anycontent = content: anycontent.replace('foo', 'baz');

	return content: anycontent;
});

Add-ons can also export reusable transform functions:

import { import transformstransforms } from '@sveltejs/sv-utils';

// reusable - export from your package
export const const addFooImport: anyaddFooImport = import transformstransforms.svelte(({ ast: anyast, svelte: anysvelte, js: anyjs }) => {
	svelte: anysvelte.ensureScript(ast: anyast, { language: anylanguage });
	js: anyjs.imports.addDefault(ast: anyast.instance.content, { as: stringas: 'Foo', from: stringfrom: './Foo.svelte' });
});

sv.file('+page.svelte', addFooImport);
sv.file('index.svelte', addFooImport);

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 { 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: ReturnType<(content: string) => ReturnType<any>>;
    } & ParseBase;
}Will help you parse code into an ast from all supported languages.
Then manipulate the ast as you want,
and finally generateCode() to write it back to the file.
import { parse } from '@sveltejs/sv-utils';

const { ast, generateCode } = parse.css('body { color: red; }');
const { ast, generateCode } = parse.html('<div>Hello, world!</div>');
const { ast, generateCode } = parse.json('{ "name": "John", "age": 30 }');
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.toml('name = "John"');
const { ast, generateCode } = parse.yaml('name: John');parse } from '@sveltejs/sv-utils';

const { const ast: Programast, const generateCode: () => stringGenerate the code after manipulating the ast.
import { svelte } from 'sv/core';
const { ast, generateCode } = parse.svelte(content);

svelte.addFragment(ast, '<p>Hello World</p>');

const code = generateCode();generateCode } = 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: ReturnType<(content: string) => ReturnType<any>>;
    } & ParseBase;
}Will help you parse code into an ast from all supported languages.
Then manipulate the ast as you want,
and finally generateCode() to write it back to the file.
import { parse } from '@sveltejs/sv-utils';

const { ast, generateCode } = parse.css('body { color: red; }');
const { ast, generateCode } = parse.html('<div>Hello, world!</div>');
const { ast, generateCode } = parse.json('{ "name": "John", "age": 30 }');
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.toml('name = "John"');
const { ast, generateCode } = parse.yaml('name: John');parse.script: (source: string) => {
    ast: Program;
    comments: Comments;
} & ParseBasescript(content);
const { const ast: AST.Rootast, const generateCode: () => stringGenerate the code after manipulating the ast.
import { svelte } from 'sv/core';
const { ast, generateCode } = parse.svelte(content);

svelte.addFragment(ast, '<p>Hello World</p>');

const code = generateCode();generateCode } = 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: ReturnType<(content: string) => ReturnType<any>>;
    } & ParseBase;
}Will help you parse code into an ast from all supported languages.
Then manipulate the ast as you want,
and finally generateCode() to write it back to the file.
import { parse } from '@sveltejs/sv-utils';

const { ast, generateCode } = parse.css('body { color: red; }');
const { ast, generateCode } = parse.html('<div>Hello, world!</div>');
const { ast, generateCode } = parse.json('{ "name": "John", "age": 30 }');
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.toml('name = "John"');
const { ast, generateCode } = parse.yaml('name: John');parse.svelte: (source: string) => {
    ast: AST.Root;
} & ParseBasesvelte(content);
const { const ast: Omit<_CSS.StyleSheetBase, "attributes" | "content">ast, const generateCode: () => stringGenerate the code after manipulating the ast.
import { svelte } from 'sv/core';
const { ast, generateCode } = parse.svelte(content);

svelte.addFragment(ast, '<p>Hello World</p>');

const code = generateCode();generateCode } = 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: ReturnType<(content: string) => ReturnType<any>>;
    } & ParseBase;
}Will help you parse code into an ast from all supported languages.
Then manipulate the ast as you want,
and finally generateCode() to write it back to the file.
import { parse } from '@sveltejs/sv-utils';

const { ast, generateCode } = parse.css('body { color: red; }');
const { ast, generateCode } = parse.html('<div>Hello, world!</div>');
const { ast, generateCode } = parse.json('{ "name": "John", "age": 30 }');
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.toml('name = "John"');
const { ast, generateCode } = parse.yaml('name: John');parse.css: (source: string) => {
    ast: Omit<_CSS.StyleSheetBase, "attributes" | "content">;
} & ParseBasecss(content);
const { const data: anydata, const generateCode: () => stringGenerate the code after manipulating the ast.
import { svelte } from 'sv/core';
const { ast, generateCode } = parse.svelte(content);

svelte.addFragment(ast, '<p>Hello World</p>');

const code = generateCode();generateCode } = 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: ReturnType<(content: string) => ReturnType<any>>;
    } & ParseBase;
}Will help you parse code into an ast from all supported languages.
Then manipulate the ast as you want,
and finally generateCode() to write it back to the file.
import { parse } from '@sveltejs/sv-utils';

const { ast, generateCode } = parse.css('body { color: red; }');
const { ast, generateCode } = parse.html('<div>Hello, world!</div>');
const { ast, generateCode } = parse.json('{ "name": "John", "age": 30 }');
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.toml('name = "John"');
const { ast, generateCode } = parse.yaml('name: John');parse.json: (source: string) => {
    data: any;
} & ParseBasejson(content);
const { const data: anydata, const generateCode: () => stringGenerate the code after manipulating the ast.
import { svelte } from 'sv/core';
const { ast, generateCode } = parse.svelte(content);

svelte.addFragment(ast, '<p>Hello World</p>');

const code = generateCode();generateCode } = 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: ReturnType<(content: string) => ReturnType<any>>;
    } & ParseBase;
}Will help you parse code into an ast from all supported languages.
Then manipulate the ast as you want,
and finally generateCode() to write it back to the file.
import { parse } from '@sveltejs/sv-utils';

const { ast, generateCode } = parse.css('body { color: red; }');
const { ast, generateCode } = parse.html('<div>Hello, world!</div>');
const { ast, generateCode } = parse.json('{ "name": "John", "age": 30 }');
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.toml('name = "John"');
const { ast, generateCode } = parse.yaml('name: John');parse.yaml: (source: string) => {
    data: ReturnType<(content: string) => ReturnType<any>>;
} & ParseBaseyaml(content);
const { const data: TomlTabledata, const generateCode: () => stringGenerate the code after manipulating the ast.
import { svelte } from 'sv/core';
const { ast, generateCode } = parse.svelte(content);

svelte.addFragment(ast, '<p>Hello World</p>');

const code = generateCode();generateCode } = 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: ReturnType<(content: string) => ReturnType<any>>;
    } & ParseBase;
}Will help you parse code into an ast from all supported languages.
Then manipulate the ast as you want,
and finally generateCode() to write it back to the file.
import { parse } from '@sveltejs/sv-utils';

const { ast, generateCode } = parse.css('body { color: red; }');
const { ast, generateCode } = parse.html('<div>Hello, world!</div>');
const { ast, generateCode } = parse.json('{ "name": "John", "age": 30 }');
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.toml('name = "John"');
const { ast, generateCode } = parse.yaml('name: John');parse.toml: (source: string) => {
    data: TomlTable;
} & ParseBasetoml(content);
const { const ast: AST.Fragmentast, const generateCode: () => stringGenerate the code after manipulating the ast.
import { svelte } from 'sv/core';
const { ast, generateCode } = parse.svelte(content);

svelte.addFragment(ast, '<p>Hello World</p>');

const code = generateCode();generateCode } = 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: ReturnType<(content: string) => ReturnType<any>>;
    } & ParseBase;
}Will help you parse code into an ast from all supported languages.
Then manipulate the ast as you want,
and finally generateCode() to write it back to the file.
import { parse } from '@sveltejs/sv-utils';

const { ast, generateCode } = parse.css('body { color: red; }');
const { ast, generateCode } = parse.html('<div>Hello, world!</div>');
const { ast, generateCode } = parse.json('{ "name": "John", "age": 30 }');
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.toml('name = "John"');
const { ast, generateCode } = parse.yaml('name: John');parse.html: (source: string) => {
    ast: AST.Fragment;
} & ParseBasehtml(content);

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)

Edit this page on GitHub llms.txt

previous next

[create your own]