Build server-rendered and single-page React applications with no configuration
APACHE-2.0 License
Sit back, drink a caipirinha, vai ficar tudo bem!
A starter project that gives you everything you need to start building great looking websites and web applications.
Skip to installation instructions
There's no shortage of generator projects out there! Two of the most popular are Create React App for single-page applications and Razzle for server-rendered applications, but of course, there are many others. Carioca isn't special, but it is simple. Here's a few things that make this project a little different:
npx create-react-app
? You delete all the crap you don't need, remove all the styles, and spinning logos. Nonsense! With Carioca, we support your own custom templates so that whenever you start a new project it follows your project structure - not what I think is best for you.<meta>
tags. Let's be honest, you don't like doing this anyhow. SEO is notoriously hard to implement on the server-side, but our reusable <Page>
component make this stupid simple. If you really want to extend it to support your own tags, go for it!<html>
tag of the page... silliness.Here's a relatively exhaustive list of opinions that carioca has about your build process:
npx @carioca/generator
... and run through the prompt that follows!
Once you've finished, you can run:
yarn dev
(or npm run dev
) to start the development server (docs)yarn build
(or npm run build
) to build your application (docs)yarn test
(or npm run test
) to test your application (docs)yarn start
(or npm run start
) to start your application (must run the build
command first) (docs)See the CLI documentation for more command options
Using Yarn:
yarn add @carioca/scripts
Using NPM:
npm install @carioca/scripts
From there, you can run any of the following commands:
carioca dev
- Runs a live-reload server for local development (docs)
carioca build
- Builds your application (docs)
carioca test
- Runs the Jest test suite (docs)
carioca start
- Starts your build application (docs)
See the CLI documentation for more command options
dev
Start the application in development mode
Options
-m, --mode
: The mode you want to build as (ssr
or spa
) (default ssr
)-p, --port
: The port where you want your application to run (default 3000
)Examples
carioca dev --mode spa
carioca dev --port 8000
build
Build the application
Options
-e, --env
: The environment you want to build (production
or development
) (default production
)-m, --mode
: The mode you want to build as (ssr
or spa
) (default ssr
)-p, --port
: The port where you want your application to run (default 3000
)Examples
carioca build --env development
carioca build --mode spa
carioca build --port 8000
test
Runs the test suite
Options
[Supports all Jest CLI flags
Examples
carioca test --watch
carioca test --coverage
carioca test --passWithNoTests --verbose
start
'Run the built application - make sure to build
first!
Options
None
Examples
carioca start
TODO: Documentation coming soon
TODO: Documentation coming soon
TODO: Documentation coming soon
TODO: Documentation coming soon
TODO: Documentation coming soon
<Page>
componentTODO: Documentation coming soon
TODO: Documentation coming soon
TODO: Documentation coming soon tsconfig.json
, .eslintrc
, .prettierrc
, and jest.config.js
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change. Please make sure to update tests and documentation as appropriate. PR's without proper tests and documentation will not be accepted - period.
Inside of the packages
folder sit all of the various projects in the carioca ecosystem. Here's a description of what each project does:
generator
- A CLI to generate a full app when the user is starting from scratch (think of this as the equivalent to npx create-react-app my-app
). This is deployed to NPM as @carioca/generator
.
scripts
- A CLI to run the various build
, dev
, test
, and start
functions that all implementers will need to call. If you're familiar with react-scripts
, this is carica's equivalent project. This is deployed to NPM as @carioca/scripts
.
server
- A sample server and some helper functions to make building the server portion of SSR a little easier. This is deployed to NPM as @carioca/server
.
utils
- A project to help organize all shared code between the other modules. This is not deployed to NPM.
To get started, simply run yarn bootstrap
. This will use Lerna to install all the appropriate dependencies and get your project set up.
If you need to reset this environment to test additional functionality you've created, run yarn reset
, which will clean up all the dependencies, remove all the node_modules
folders, and then run yarn bootstrap
itself.
If you make a change to the generators
, scripts
, server
, or utils
packages, then your workflow will look something like this:
yarn bootstrap
commandyarn reset
sample-app
folder, run the command that will trigger your change (yarn dev
, yarn build
, yarn test
, yarn start
, etc.)You can run the test suite across all our projects by running yarn test
from the root of the project.
No doubt, this project shares about 80% of its logical inspiration from Razzle. However, this library has become quite bloated in my opinion, and is no longer maintained actively by Jared Palmer. I wanted a simpler, more opinionated library for abstracting away build concerns for building SSR and SPA-based web applications. If there's any message you should get from reading this paragraph, it's that I love Razzle with all my heart, but I grew frustrated when trying to work with the codebase and bend it to my will.