rails-new

Create a Rails app named blog in the current directory

$ rails new blog

$ rails new [app_name] --api

$ rails new [app_name] [[-d|--database]] postgresql

$ rails new [app_name] [[-J|--skip-javascript]]

$ rails new [[-h|--help]]

rails new APP_PATH [options]

-d, --database=DATABASE
    Specifies the database for the application. Common choices include postgresql, mysql, sqlite3. Also supports JDBC and other enterprise databases.

--skip-bundle
    Skips the bundle install step after generating the application, useful for manual gem installation later.

--skip-test
    Skips the generation of Test Unit files and the test directory, often used when employing alternative testing frameworks like RSpec.

--skip-system-test
    Skips the generation of system test files.

--api
    Generates a bare-bones API-only application, excluding components like Action View, Action Controller's browser-specific functionality, and browser-related middleware.

--webpack=WEBPACK
    Chooses a JavaScript bundling tool for the frontend. Options typically include esbuild, rollup, or webpack.

--css=CSS
    Chooses a CSS framework or preprocessor. Examples include tailwind, bootstrap, bulma, sass.

--minimal
    Generates a minimalistic Rails application, skipping many non-essential components and default gems for a leaner setup.

--skip-git
    Skips Git repository initialization. By default, rails new initializes a new Git repository.

--skip-active-record
    Excludes Active Record, Rails' ORM, useful if planning to use a different persistence layer or no database.

--skip-action-cable
    Skips Action Cable, the framework for WebSocket integration.

--skip-action-mailer
    Skips Action Mailer, the email sending framework.

--skip-action-text
    Skips Action Text, for rich text content.

--skip-action-view
    Skips Action View, the templating layer.

--skip-javascript
    Skips the generation of JavaScript files and dependencies.

--skip-sprockets
    Skips Sprockets, the asset pipeline.

-T, --skip-turbolinks
    Skips Turbolinks, which speeds up page navigation.

-m, --template=PATH
    Specifies a custom application template file to be applied after the application is generated, allowing for highly customized setups.

-f, --force
    Overwrites existing files if the target directory already exists. Use with caution.

-h, --help
    Displays a help message with available options.

-v, --version
    Displays the Rails version.

The rails new command is the foundational tool for initiating a new Ruby on Rails web application. It automates the setup of a complete Rails project directory, including essential subdirectories like app/, config/, db/, lib/, public/, and test/. The command generates a boilerplate structure with all necessary configuration files, default database settings (typically SQLite), and initial application code, adhering to Rails' convention over configuration philosophy. This command saves significant time by providing a ready-to-run skeleton, allowing developers to immediately begin building features without manual setup. It also installs default gem dependencies, ensuring the application is functional out-of-the-box. Developers can customize the generated application using various options to tailor it to specific needs, such as choosing a different database, skipping certain components, or integrating specific front-end tools.

Creating a new Rails application with rails new requires a pre-existing Ruby environment with RubyGems installed. The command can take several minutes to complete, especially if bundle install is run, as it downloads and installs all necessary gem dependencies. If the specified APP_PATH directory already exists and is not empty, the command will typically fail unless the --force option is used, which will overwrite existing files. It's crucial to be aware of the Rails version being used, as available options and default behaviors can change between major releases.

When rails new creates an application, it establishes a well-defined directory structure:
app/: Contains the core application code (models, views, controllers, helpers, assets).
bin/: Executable scripts like rails itself and bundle.
config/: Application configuration files (e.g., database, routes, environments).
db/: Database schema and migrations.
lib/: Custom libraries and modules.
log/: Application log files.
public/: Static assets accessible directly by the web server.
test/: Unit, integration, and functional tests.
tmp/: Temporary files.
This structure enforces conventions that promote organization and understandability.

One powerful feature of rails new is its support for application templates via the --template (or -m) option. A template is a Ruby script that can automate additional setup steps after the basic application is generated. This can include adding specific gems, configuring test frameworks, setting up initial data, or even generating custom code. Templates are invaluable for standardizing application setups across an organization or for quickly bootstrapping projects with specific tech stacks.

The rails new command has been a cornerstone of the Ruby on Rails framework since its early days, shortly after David Heinemeier Hansson open-sourced it in 2004. Initially, it was a simple script to scaffold a basic MVC structure. Over time, as Rails evolved and incorporated new features like Action Cable, Action Text, and integrated JavaScript tooling, the rails new command itself was updated to include options for these features and to manage the default setup. Its continuous evolution reflects the framework's commitment to providing a productive and modern development environment, always aiming to provide a solid, opinionated starting point while offering flexibility through numerous customization flags.

rails(1), rails generate(1), rails server(1), bundle(1), ruby(1), gem(1)