:project-version: 1.1.0
++++
[discrete]
= Spider Silk
Thin call stack, strong signature.
Spider Silk is a web framework built on the Jakarta Servlet API.
== Why Spider Silk
- Fast startup.
There is no annotation scanning and no proxy generation, so an application starts fast in an autoscaled container, a serverless function, a test run, and a development-server restart alike.
- Code traceable from its source.
A person and an AI coding agent alike follow the code a request passes through without running it.
** A simple API.
A handler is
WebResponse handle(WebRequest request), registered as a lambda or a method reference.
** No reflection.
The framework's own code reflects over nothing, so what runs is what the code says, and a GraalVM native image needs no reflection config for it.
** A thin call stack.
Two stack frames stand between HttpServlet.service and a handler, and nothing the framework calls into is more than four frames deep.
** A small default stack.
One dependency brings embedded Jetty and jte, and jte compiles templates to Java, so rendering takes no reflection either.
- Open to the ecosystem.
Tomcat and Undertow, and FreeMarker, Handlebars, and Thymeleaf, come as optional modules, and switching to one is a single line.
- Tooling around it.
A test harness, an OpenAPI export, an OpenTelemetry agent extension, a Gradle plugin and a Maven parent for packaging, and an agent skill for AI coding agents come with the framework.
The manual explains each of these in detail: https://spider-silk.benelog.net[spider-silk.benelog.net] (https://spider-silk.benelog.net/ko/[한국어 매뉴얼]), for every released version.
== Quick Start
Requires Java 25 or later.
The current version on Maven Central is {project-version}.
=== build.gradle
[source,groovy,subs="attributes+"]
repositories {
mavenCentral()
}
dependencies {
implementation 'net.benelog.spidersilk:spider-silk-core:{project-version}'
testImplementation 'net.benelog.spidersilk:spider-silk-test:{project-version}'
}
=== pom.xml
[source,xml,subs="attributes+"]
=== Hello, world
[source,java]
import net.benelog.spidersilk.App;
import net.benelog.spidersilk.WebResponse;
public class Main {
public static void main(String[] args) {
App app = new App();
app.get("/hello/{name}", req -> WebResponse.text("Hello, " + req.pathParam("name")));
app.start(8080);
}
}
[source,bash]
$ curl localhost:8080/hello/silk
Hello, silk
spider-silk-core includes embedded Jetty, so nothing else is needed.
The https://spider-silk.benelog.net[manual] covers the rest: the modules, templates, testing, deployment, and the agent skill.
== AI coding agents
link:skills/spider-silk/SKILL.md[skills/spider-silk/] is an https://agentskills.io[Agent Skill] that guides a coding agent to use the framework as intended.
The repository is a plugin marketplace for both Claude Code and Codex.
Either marketplace installs the skill from the latest release's tag, so the skill describes the API of the jars on Maven Central.
Claude Code installs it with two commands inside a session:
/plugin marketplace add benelog/spider-silk
/plugin install spider-silk@spider-silk
Codex installs it with two commands in a shell:
[source,bash]
codex plugin marketplace add benelog/spider-silk
codex plugin add spider-silk@spider-silk
A new release reaches an installed skill through /plugin marketplace update spider-silk in Claude Code, and through codex plugin marketplace upgrade spider-silk followed by codex plugin add spider-silk@spider-silk in Codex.
https://spider-silk.benelog.net/agent-skill.html[The manual] covers auto-update, a project-level copy, and Cursor and GitHub Copilot.
== Further reading
- https://spider-silk.benelog.net[The manual] and https://spider-silk.benelog.net/ko/[the Korean manual (한국어 매뉴얼)]: every feature in detail, for every released version.
- link:notes/positioning.md[notes/positioning.md]: Spider Silk next to Javalin, Spark, Helidon SE, and Spring Boot, and what it trades away.
- link:notes/decisions.md[notes/decisions.md]: the reasoning behind each piece, and what was rejected.
- link:CHANGELOG.md[CHANGELOG.md]: what changed in each release.
- https://github.com/benelog/spider-silk/issues[The issue tracker]: what was deferred, with the condition that would make it worth doing.
