{"id":15002334,"url":"https://github.com/jakepartusch/serverlessui","last_synced_at":"2025-04-13T00:46:09.407Z","repository":{"id":40200043,"uuid":"332943848","full_name":"JakePartusch/serverlessui","owner":"JakePartusch","description":"A command-line utility for deploying serverless applications to AWS. Complete with custom domains, deploy previews, TypeScript support, and more.","archived":false,"fork":false,"pushed_at":"2021-12-31T01:43:57.000Z","size":3084,"stargazers_count":543,"open_issues_count":3,"forks_count":20,"subscribers_count":9,"default_branch":"main","last_synced_at":"2025-04-13T00:46:01.419Z","etag":null,"topics":["aws","aws-cdk","cdk","cli","deploy","jamstack","lambda","serverless","serverless-functions","typescript","typescript-support","ui"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JakePartusch.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-01-26T02:11:27.000Z","updated_at":"2025-03-19T20:36:42.000Z","dependencies_parsed_at":"2022-06-26T23:31:22.055Z","dependency_job_id":null,"html_url":"https://github.com/JakePartusch/serverlessui","commit_stats":null,"previous_names":[],"tags_count":46,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JakePartusch%2Fserverlessui","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JakePartusch%2Fserverlessui/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JakePartusch%2Fserverlessui/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JakePartusch%2Fserverlessui/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JakePartusch","download_url":"https://codeload.github.com/JakePartusch/serverlessui/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248650420,"owners_count":21139672,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","aws-cdk","cdk","cli","deploy","jamstack","lambda","serverless","serverless-functions","typescript","typescript-support","ui"],"created_at":"2024-09-24T18:49:37.079Z","updated_at":"2025-04-13T00:46:09.387Z","avatar_url":"https://github.com/JakePartusch.png","language":"TypeScript","readme":"\u003cp align=\"center\"\u003e\n    \u003cimg alt=\"Serverless UI\" src=\"./docs/images/undraw_To_the_stars_qhyy.svg\" width=\"150\" /\u003e\n\u003c/p\u003e\n\u003ch1 align=\"center\"\u003e\n  Serverless UI\n\u003c/h1\u003e\n\n\u003ch3 align=\"center\"\u003e\n  💻 🚀 ☁ \n\u003c/h3\u003e\n\u003ch3 align=\"center\"\u003e\n  Deploying Websites to AWS on Easy Mode\n\u003c/h3\u003e\n\u003cp align=\"center\"\u003e\n  Serverless UI is a free, open source command-line utility for quickly building and deploying serverless applications on AWS\n\u003c/p\u003e\n\n- **Bring your own UI** It doesn't matter if it's React, Vue, Svelte or JQuery. If it compiles down to static files, then it is supported.\n\n- **Serverless Functions** Your functions become endpoints, automatically. Serverless UI deploys each function in your `/functions` directory as a Node.js lambda behind a CDN and API Gateway for an optimal blend of performance and scalability.\n\n- **Deploy Previews** Automatically deploy each iteration of your application with a separate URL to continuously integrate and test with confidence.\n\n- **Custom Domains** Quickly configure a custom domain to take advantage of production deploys!\n\n- **TypeScript Support** Write your serverless functions in JavaScript or TypeScript. Either way, they'll be bundled down extremely quickly and deployed as Node.js 14 lambdas.\n\n- **Own your code** Skip the 3rd Party services — get all of the benefits and security of a hosted AWS application, without going through a middleman. Deploy to a new AWS account, or an existing account and get up and running in five minutes!\n\n## What's in this Document\n\n- [What's in this Document](#whats-in-this-document)\n- [🚀 Get Up and Running in 5 Minutes](#-get-up-and-running-in-5-minutes)\n- [📖 CLI Reference](#-cli-reference)\n  - [`deploy`](#deploy)\n    - [Options](#options)\n    - [Examples](#examples)\n  - [`configure-domain`](#configure-domain)\n    - [Options](#options-1)\n    - [Examples](#examples-1)\n    - [Additional Steps](#additional-steps)\n- [Continuous Integration](#continuous-integration)\n  - [GitHub Actions](#github-actions)\n- [👩‍🔬 Experimental Features](#-experimental-features)\n  - [\\_\\_experimental_privateS3](#__experimental_privates3)\n- [👩‍💻 Advanced Use Cases](#-advanced-use-cases)\n  - [Serverless UI Advanced Example](#serverless-ui-advanced-example)\n- [FAQ](#faq)\n- [License](#license)\n\n## 🚀 Get Up and Running in 5 Minutes\n\nYou can get a new Serverless UI site deployed to you AWS account in just a few steps:\n\n1. **AWS Prerequisites**\n\n   In order to deploy to AWS, you'll have to configure your machine with local credentials. You'll find the best instructions [here](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-configure.html).\n\n1. **Install the Serverless UI Command-Line Interface**\n\n   ```shell\n   npm install -g @serverlessui/cli\n   ```\n\n1. **Deploy your static website**\n\n   Finally, tell the Serverless UI where to find your website's static files.\n\n   ```shell\n   sui deploy --dir=\"dist\"\n   ```\n\n## 📖 CLI Reference\n\n1. [deploy](#deploy)\n2. [configure-domain](#configure-domain)\n\n### `deploy`\n\n```shell\nsui deploy\n```\n\n#### Options\n\n|    Option     | Description                                           |    Default    |\n| :-----------: | ----------------------------------------------------- | :-----------: |\n|    `--dir`    | The directory of your website's static files          |   `\"dist\"`    |\n| `--functions` | The directory of the functions to deploy as endpoints | `\"functions\"` |\n|   `--prod`    | Custom Domains only: `false` will deploy a preview    |    `false`    |\n\n\u003e Note: The `--dir` directory should be only static files. You may need to run a build step prior to deploying\n\n#### Examples\n\n- Deploy a preview of static website in a `build` directory with no functions\n\n```shell\nsui deploy --dir=\"build\"\n...\n❯ Website Url: https://xxxxx.cloudfront.net\n```\n\n- Deploy a preview of static website with serverless functions\n\n```shell\nsui deploy --dir=\"build\" --functions=\"lambdas\"\n...\n❯ Website Url: https://xxxxx.cloudfront.net\n❯ API Url: https://xxxxx.cloudfront.net/api/my-function-name\n❯ API Url: https://xxxxx.cloudfront.net/api/my-other-function-name\n```\n\n- Production deploy\n  \u003e Note: A custom domain must be configured for production deploys. See [configure-domain](#configure-domain)\n\n```shell\nsui deploy --prod --dir=\"build\" --functions=\"lambdas\"\n...\n❯ Website Url: https://www.my-domain.com\n❯ API Url: https://www.my-domain.com/api/my-function-name\n❯ API Url: https://www.my-domain.com/api/my-other-function-name\n```\n\n### `configure-domain`\n\nThis step only needs to be completed once, but it may take anywhere from 20 minutes - 48 hours to fully propogate\n\n```shell\nsui configure-domain [--domain]\n```\n\n#### Options\n\n|   Option   | Description        | Default |\n| :--------: | ------------------ | :-----: |\n| `--domain` | Your custom domain |  None   |\n\n#### Examples\n\nDeploy a Hosted Zone and Certificate to us-east-1 (required region for Cloudfront)\n\n```shell\nsui configure-domain --domain=\"serverlessui.app\"\n```\n\n#### Additional Steps\n\nA minute or two after running this command, the deploy will \"hang\" while trying to validate the domain prior to creating the wildcard certificate.\n\n1.  **Navigate to Route53**\n\n    Find your Hosted Zone and take note of the Zone Id and Name Servers\n\n    \u003cp align=\"center\"\u003e\n        \u003cimg alt=\"Serverless UI\" src=\"./docs/images/hosted-zone-id.png\" width=\"600\" /\u003e\n    \u003c/p\u003e\n    \u003cp align=\"center\"\u003e\n        \u003cimg alt=\"Serverless UI\" src=\"./docs/images/name-servers.png\" width=\"600\" /\u003e\n    \u003c/p\u003e\n\n2.  **Update the Nameservers on your Domain Registrar's website (eg. Namecheap)**\n\n    \u003cp align=\"center\"\u003e\n        \u003cimg alt=\"Serverless UI\" src=\"./docs/images/domain-registrar.png\" width=\"600\" /\u003e\n    \u003c/p\u003e\n\n3.  **Wait**\n\n    The DNS resolution can be as quick as 10 minutes or take up to 48 hours. After some time, the Serverless UI command may timeout, but running it again should pick up where it left off.\n\n4.  **Navigate to Certificate Manager**\n\n    After the `configure-domain` command has completed successfully, navigate to Certificate Manager and take note of the Certificate Arn (eg. \"arn:aws:acm:us-east-1:ACCOUNT_ID:certificate/xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx\")\n\n5.  **Create a Serverless UI config file**\n\n    Place the config file in the root of your project\n\n    \u003e serverlessui.config.js\n\n    ```js\n    module.exports = {\n      domain: \"serverlessui.app\",\n      zoneId: \"Z10011111YYYYGGGRRR\",\n      certificateArn:\n        \"arn:aws:acm:us-east-1:ACCOUNT_ID:certificate/xxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxx\",\n    };\n    ```\n\n## Continuous Integration\n\nSince Serverless UI is a command-line tool available via npm, it will work in almost any CI environment.\n\n### GitHub Actions\n\n\u003e Note: Checkout the action in this repo for a live example https://github.com/JakePartusch/serverlessui/actions\n\n```yaml\nname: Serverless UI Build \u0026 Deploy Preview\n\non: [pull_request]\n\njobs:\n  deploy-pr-preview:\n    runs-on: ubuntu-latest\n\n    steps:\n      - uses: actions/checkout@v2\n      - name: Use Node.js\n        uses: actions/setup-node@v1\n        with:\n          node-version: \"12.x\"\n      - run: npm ci\n      - run: npm run build\n      - name: Configure AWS Credentials\n        uses: aws-actions/configure-aws-credentials@v1\n        with:\n          aws-access-key-id: ${{ secrets.AWS_ACCESS_KEY_ID }}\n          aws-secret-access-key: ${{ secrets.AWS_SECRET_ACCESS_KEY }}\n          aws-region: us-west-2\n      - run: npm install -g @serverlessui/cli\n      - run: sui deploy --dir=\"build\"\n      - name: Add PR Comment\n        uses: actions/github-script@v3\n        with:\n          github-token: ${{secrets.GITHUB_TOKEN}}\n          script: |\n            const outputs = require(`${process.env.GITHUB_WORKSPACE}/cdk.out/outputs.json`);\n            const stackName = Object.keys(outputs).find((key) =\u003e\n              key.startsWith(\"ServerlessUI\")\n            );\n            const baseUrlKey = Object.keys(outputs[stackName]).find((key) =\u003e\n              key.startsWith(\"ServerlessUIBaseUrl\")\n            );\n            github.issues.createComment({\n              issue_number: context.issue.number,\n              owner: context.repo.owner,\n              repo: context.repo.repo,\n              body: `✅ Your deploy preview is ready: ${outputs[stackName][baseUrlKey]}`,\n            });\n```\n\n## 👩‍🔬 Experimental Features\n\nIn order to use experimental features, a `serverlessui.config.js` file must exist at the base of the project.\n\n### \\_\\_experimental_privateS3\n\nThis experimental feature allows the configuration of a private S3 bucket — which may be desired for enhanced security. This feature can be enabled in `serverlessui.config.js`:\n\n```javascript\nmodule.exports = {\n  __experimental_privateS3: true,\n};\n```\n\n## 👩‍💻 Advanced Use Cases\n\nFor existing serverless projects or those that may have additional CloudFormation and/or CDK infrastructure, Serverless UI provides CDK constructs for each of the cli actions:\n\n```javascript\nimport { ServerlessUI, DomainCertificate } from '@serverlessui/construct;\n```\n\n### Serverless UI Advanced Example\n\nFor a full-featured example, check out:\nhttps://github.com/JakePartusch/serverlessui-advanced-example\n\n```javascript\nconst { functions } = new ServerlessUI(this, \"ServerlessUI\", {\n  buildId: \"advanced-example\",\n  uiSources: [Source.asset(`${__dirname}/../build`)],\n  apiEntries: [`${__dirname}/../functions/graphql.ts`],\n  apiEnvironment: {\n    TABLE_NAME: table.tableName,\n  },\n  domain: {\n    domainName: \"serverlessui.app\",\n    hostedZone: HostedZone.fromHostedZoneAttributes(this, \"HostedZone\", {\n      hostedZoneId: \"Z1XXXXXXXXXXXXX\",\n      zoneName: \"serverlessui.app\",\n    }),\n    certificate: Certificate.fromCertificateArn(\n      this,\n      \"Certificate\",\n      \"arn:aws:acm:us-east-1:xxxxxxxxxx:certificate/xxxxxx-xxxx-xxxx-xxxxxx\"\n    ),\n  },\n});\n```\n\n## FAQ\n\n- Q. How is this different than Netlify or Vercel?\n  - Serverless UI allows you to enjoy the benefits of pre-configured infrastructure without going through a middleman. This allows for fewer accounts, tighter security and seamless integration with a wealth of AWS services. Additionally, you receive these benefits \"at cost\" since this is deployed directly to your AWS account.\n\n## License\n\nLicensed under the [MIT License](./LICENSE).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjakepartusch%2Fserverlessui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjakepartusch%2Fserverlessui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjakepartusch%2Fserverlessui/lists"}