# XIAOJUSURVEY: An Open-Source TypeScript Survey and Form Builder from Didi

> XIAOJUSURVEY is an open-source survey and analytics platform developed by Didi that supports questionnaires, exams, polls, and complex forms with logic branching. It runs a Vue 3 frontend against a NestJS and MongoDB backend, deploys through Docker, and is designed for both individual developers and enterprise teams who need a fully self-hosted solution.

**didi/xiaoju-survey** — XIAOJUSURVEY is an enterprises form builder and analytics platform that allows users to create questionnaires, exams, polls, quizzes, and analyze data online.

- Repository: https://github.com/didi/xiaoju-survey
- Website: https://xiaojusurvey.didi.cn
- Stars: 3,798 · Forks: 514
- Language: TypeScript
- License: Apache-2.0
- Published: 2026-09-09 · Updated: 2026-09-09 · Language: en
- Canonical page: https://hysenlabs.com/projects/didi-xiaoju-survey

## What Problem XIAOJUSURVEY Solves and Who It Is For

XIAOJUSURVEY targets organizations that need a complete survey lifecycle in one self-hosted platform: form design, distribution, response collection, and online reporting. The repository description frames it as a lightweight, secure research system providing a production-grade solution for building questionnaires, exams, assessments, and complex forms.

The platform is positioned for both individual developers and enterprises. The README documents over 40 question types and 100 pre-built templates spanning market research, customer satisfaction surveys, online exams, voting, and assessments. On the data side, the repository description states that the analytics capabilities have been shaped by processing hundreds of millions of responses, producing per-question statistics, cross-analysis, and multi-channel reporting.

The project is distinct from lightweight form libraries because it ships a complete application, not just components. It includes user authentication, workspace management, multi-role permissions, and a data export path, so an adopter gets an end-to-end workflow rather than building one from scratch.

## Architecture: Vue 3 Frontend, NestJS Backend, and MongoDB

The technology stack is documented in the README. The web layer uses Vue 3 and ElementPlus for the desktop interface, with a React Native SDK available for cross-platform embedding. The server layer runs NestJS with MongoDB as the primary database. An AI questionnaire generation feature is included, requiring a connection to an external LLM provider.

The repository layout reflects this separation. The `web/` directory holds the Vue 3 application, and the `server/` directory holds the NestJS service. The `docker-compose.yaml` file at the repository root ties them together and also brings up a MongoDB 4 container. The Docker image for the application service exposes a single port, 8080, and nginx is included in the image to serve the built frontend alongside the API.

The Dockerfile uses a two-stage build. The first stage compiles both the Vue frontend and the NestJS server, then the second stage copies only the compiled artifacts and static files into the final image, keeping the production image thin. The `docker-run.sh` entry point script starts nginx and the Node process through a process manager.

## Running the Platform: Local Development and Docker Deployment

For local development, the README gives two start commands. From the `server/` directory:

```bash
cd server
npm install
npm run local
```

From the `web/` directory:

```bash
cd web
npm install
npm run serve
```

Once both are running, the management console (B-side) is available at `http://localhost:8080/management` and the respondent-facing render layer (C-side) at `http://localhost:8080/render/:surveyPath`.

For production, the Docker path is the documented approach. The repository ships two image variants. The slim image is based on `node:18-slim` and is recommended for production because it contains only the runtime dependencies. The full image is based on `node:18` and adds `curl`, `vim`, and `git` for development and debugging scenarios.

The `docker-compose.yaml` pins the slim image at version 1.3.4 and wires the application container to a MongoDB container through environment variables. The MongoDB root credentials must be set in the environment before starting the stack, along with the AI model configuration if the AI generation feature is needed:

```yaml
XIAOJU_SURVEY_MONGO_URL: mongodb://${MONGO_INITDB_ROOT_USERNAME}:${MONGO_INITDB_ROOT_PASSWORD}@xiaoju-survey-mongo:27017
```

Switching between slim and full simply means changing the image tag in `docker-compose.yaml`.

## Form Design Capabilities: Logic, Theming, and Security

The README documents several design capabilities that distinguish XIAOJUSURVEY from simpler form tools. On the logic side, the platform supports display logic, jump logic, option references, and question references, allowing forms to branch dynamically based on previous answers.

Theme customization covers colors, backgrounds, images, logos, and result-page rules. The platform also ships an embeddable SDK for displaying shorter survey forms within other applications across multiple devices, documented as the multi-terminal embedded mini-survey SDK.

On the security side, the README lists transmission encryption, sensitive keyword filtering, and anti-ballot-stuffing controls as part of the compliance features. It also documents custom hook configuration for integrating with external data push and notification systems, allowing XIAOJUSURVEY to send response data to other tools in an organization's stack.

The README emphasizes the questionnaire meta protocol, a standardization of questionnaire data structures, question type protocols, and material protocols that the platform uses internally. This protocol-first design is stated as the basis for the platform's extensibility: question types are treated as configurable materials rather than hardcoded components, so organizations that need a custom question type can extend the system without modifying the core.

## Limitations: Infrastructure Overhead and Self-Hosting Complexity

XIAOJUSURVEY is not a drop-in install. The `docker-compose.yaml` requires valid MongoDB credentials in environment variables before the stack will start. The AI questionnaire generation feature adds three more variables: `AImodel_API_URL`, `AImodel_API_KEY`, and `AImodel_MODEL`. None of these have defaults in the compose file, so the setup is not a single `docker compose up` from a fresh clone.

The project has no GitHub releases. Version management happens through Docker image tags on Docker Hub, and the compose file currently pins to `1.3.4-slim`. Teams that want to track updates must watch the Hub for new tags.

The repository's primary documentation is in Chinese, with an English README available as `README_EN.md`. The official documentation site is at `xiaojusurvey.didi.cn/docs`. Teams operating outside of China and outside of Mandarin-reading teams may find the community primarily Chinese-speaking, which is a practical consideration for support.

LimeSurvey is a direct alternative. It is a PHP-based, self-hosted survey platform that has been available since 2006 and uses a MySQL or PostgreSQL backend. The key difference is maturity and ecosystem: LimeSurvey has a larger body of third-party documentation and a longer track record in enterprise environments. XIAOJUSURVEY's advantage is a more modern stack (TypeScript, Vue 3, NestJS) and the built-in AI questionnaire generation path.

## Maintenance and License

XIAOJUSURVEY is licensed under the Apache-2.0 license. The repository is not archived, and the last push was on 2026-07-20. The project has no GitHub releases; new versions are published as Docker images. The repository includes contributing guidelines and a code of conduct. The Dockerfile shows a build process using the `registry.npmmirror.com` npm mirror, which teams outside China may want to change to the default registry in self-built images.

## Conclusion

XIAOJUSURVEY is a good fit for teams that need a self-hosted survey platform with skip logic, multi-role permissions, and cross-analysis reporting, and who are comfortable operating a NestJS and MongoDB stack. It is not a quick install: the Docker path requires managing MongoDB credentials and AI model environment variables before anything works. Teams that want a hosted SaaS product without infrastructure overhead should look elsewhere. Start by running the slim Docker image and verifying that the management console at port 8080 loads before committing to the full deployment.

## FAQ

### How do I start XIAOJUSURVEY locally for development?

Clone the repository, then run `npm install` and `npm run local` in the `server/` directory, and `npm install` and `npm run serve` in the `web/` directory. The management console will be available at `http://localhost:8080/management`.

### Which Docker image should I use for a production deployment of XIAOJUSURVEY?

The README recommends the slim image variant (`xiaojusurvey/xiaoju-survey:latest-slim`) for production because it is built on `node:18-slim` and contains only the runtime dependencies. The full image includes development tools and is intended for debugging scenarios.

### Does XIAOJUSURVEY require an external AI service to function?

The core survey and analytics features work without AI. The AI questionnaire generation feature is optional and requires setting the `AImodel_API_URL`, `AImodel_API_KEY`, and `AImodel_MODEL` environment variables to connect to an external LLM provider.

## Sources

- [didi/xiaoju-survey on GitHub](https://github.com/didi/xiaoju-survey)
- [Issues](https://github.com/didi/xiaoju-survey/issues)
- [License: Apache-2.0](https://github.com/didi/xiaoju-survey/blob/main/LICENSE)
- [Project website](https://xiaojusurvey.didi.cn)
- [README](https://github.com/didi/xiaoju-survey/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/didi-xiaoju-survey