From 31d4b9dee695459a6d2eb1a47b545a94979ce630 Mon Sep 17 00:00:00 2001 From: Damian Legawiec Date: Wed, 18 Aug 2021 12:10:34 +0000 Subject: [PATCH] GitBook: [master] 4 pages modified --- SUMMARY.md | 2 +- contributing/developing_spree.md | 60 +++++++++++--------------- getting-started/installation.md | 14 +++++- getting-started/understanding_spree.md | 54 ++++++++++++----------- 4 files changed, 66 insertions(+), 64 deletions(-) diff --git a/SUMMARY.md b/SUMMARY.md index a111b5a..45c79e8 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -5,7 +5,7 @@ ## Getting Started * [Installation](getting-started/installation.md) -* [Understanding how Spree works](getting-started/understanding_spree.md) +* [Headless Commerce](getting-started/understanding_spree.md) ## Internals diff --git a/contributing/developing_spree.md b/contributing/developing_spree.md index 49207e6..2ecdd86 100644 --- a/contributing/developing_spree.md +++ b/contributing/developing_spree.md @@ -2,19 +2,28 @@ title: Developing Spree section: contributing order: 0 +description: >- + This guide covers all the necessary steps to contributing to Spree source + code. We're happy you're here! --- # Developing Spree -## Overview +## Spree codebase -This guide covers all the necessary steps to contributing to Spree source code. We're happy you're here! +Spree API is written in Ruby on Rails framework and is mounted into a Rails application as [a Rails Engine](https://guides.rubyonrails.org/engines.html). -## Fork Spree repo +You don't need to be a Rails developer to work with Spree. You can install Spree via Spree Starter or Docker and not touch the underlying codebase at all and work only with the APIs. + +### Spree namespace + +All Spree models, controllers and other Ruby classes are namespaced by the `Spree` keyword, eg. `Spree::Product`. This means that those files are also located in `spree` sub-directories eg. [app/models/spree/product.rb](https://github.com/spree/spree/blob/master/core/app/models/spree/product.rb). + +## Forking Spree repo Go to [Spree GitHub repository](https://github.com/spree/spree) and click **Fork** button. This will create a copy of Spree repository on your GitHub account. See [Github Documentation](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo) for more information on forking. -## Setup locally +## Local setup 1. Clone the your fork repository @@ -23,38 +32,27 @@ Go to [Spree GitHub repository](https://github.com/spree/spree) and click **Fork cd spree ``` -2. Install the gem dependencies +2. [Install ruby](https://www.ruby-lang.org/en/documentation/installation/) +3. Install required libraries ```text - bundle install + /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" && brew install openssl mysql postgresql sqlite imagemagick redis ``` -### Fix Bundle errors on MacOS - -If `bundle install` fails that means you're missing some required system libraries. - -Firstly, ensure you hve [homebrew installed](https://brew.sh/). You will need to install some packages needed to run Spree and Rails applications in general: +4. Install the gem dependencies -```text -brew install openssl mysql postgresql sqlite imagemagick redis -``` + ```text + bundle install + ``` ## Create Sandbox application -Spree is meant to be run within the context of Rails application and the source code is essentially a collection of gems. You can easily create a sandbox application inside of your cloned source directory for testing purposes. - -This will setup a Rails application with Spree and some essential extensions and gems pre-installed with some data seeded Sandbox application is not meant to be run on production! +Bellow command will setup a Rails application with Spree pre-installed with some data seeded: ```text bundle exec rake sandbox ``` -For **headless sandbox** please run: - -```text -SPREE_HEADLESS=true bundle exec rake sandbox -``` - By default Sandbox uses **SQLite** database. But you can switch to **PostgreSQL**: ```text @@ -67,12 +65,6 @@ or **MySQL**: DB=mysql bundle exec rake sandbox ``` -You can also combine those options: - -```text -SPREE_HEADLESS=true DB=postgres bundle exec rake sandbox -``` - Start the server ```text @@ -82,15 +74,11 @@ bin/rails s ### Performance in development mode -You may notice that your Spree store runs slower in development environment. This can be because in development each asset \(css and javascript\) is loaded separately. You can disable it by adding the following line to `config/environments/development.rb`. - -```ruby -config.assets.debug = false -``` +You may notice that your Spree store runs slower in development environment. This is caused by disabled caching and automatic reloading of code after each change. ### Caching -Also in development caching is disabled by default. To turn on caching run: +Caching is disabled by default. To turn on caching please run: ```bash bin/rails dev:cache @@ -139,7 +127,7 @@ cd core bundle exec rspec spec/models/spree/state_spec.rb:7 ``` -### Running integration tests on MacOS +### Running integration tests on MacOS \(only applicable for Admin Panel\) We use chromedriver to run integration tests. To install it please use this command: diff --git a/getting-started/installation.md b/getting-started/installation.md index a5c1581..e10b252 100644 --- a/getting-started/installation.md +++ b/getting-started/installation.md @@ -22,9 +22,19 @@ Windows users will need to [install the Linux subsystem](https://docs.microsoft. You now have a functional Spree application after running only a few commands! -To see your application in action, open a browser window and navigate to [http://localhost:3000](http://localhost:3000). You should see the Spree default home page. +To stop the webserver, hit `Ctrl-C` in the terminal window where it's running. -To stop the webserver, hit `Ctrl-C` in the terminal window where it's running. In development mode, Spree does not generally require you to stop the server; changes you make in files will be automatically picked up by the server. +### Connecting to the API + +Your API server is up and running.[ Download our Open API doc](https://raw.githubusercontent.com/spree/spree/master/api/docs/v2/storefront/index.yaml) and [import it to Postman](https://learning.postman.com/docs/integrations/available-integrations/working-with-openAPI/) to start playing around. Your backend server URL is `http://localhost:3000` so to grab the Products List you can use: + +```bash +curl --request GET \ + --url http://localhost:3000/api/v2/storefront/products \ + --header 'Content-Type: application/json' +``` + +We recommend checking out our [API reference](https://api.spreecommerce.org/) for more details. ### Logging Into the Admin Panel diff --git a/getting-started/understanding_spree.md b/getting-started/understanding_spree.md index 97a424c..d1d6cc4 100644 --- a/getting-started/understanding_spree.md +++ b/getting-started/understanding_spree.md @@ -2,46 +2,58 @@ title: Understanding Spree section: getting_started order: 1 +description: >- + Spree is a modular, API-first headless ecommerce platform which consists of + several APIs. --- -# Understanding how Spree works +# Headless Commerce -## Headless Commerce +## Spree APIs -Spree is a modular, API-first headless commerce application. What does it mean? +Spree is a modular, API-first headless ecommerce platform which consists of several APIs. -Spree comes with a set of [APIs](https://api.spreecommerce.org/) you can work with directly or via [SDK](https://github.com/spree/spree-storefront-api-v2-js-sdk) to build your own Storefront. +### Storefront API -For application to application integration, you can use Platform API. +* Modern and lightweight REST API based on JSON API schema +* Designed for building Storefronts and mobile apps +* [JavaScript / TypeScript SDK](https://github.com/spree/spree-storefront-api-v2-js-sdk) available +* NextJS Commetce and VueStorefront integrations available soon! -There are optional Admin / Storefront packages available also. +### Platform API -## Spree codebase +* OAuth 2.0 authentication +* designed for building application to application integration +* permission sets based access to resources +* access any resource on the Spree platform and perform any action -Spree API is written in Ruby on Rails framework and is mounted into a Rails application as [a Rails Engine](https://guides.rubyonrails.org/engines.html). +### Webhooks -You don't need to be a Rails developer to work with Spree. You can install Spree via Spree Starter or Docker and not touch the underlying codebase at all and work only with the APIs. +We're working hard to deliver webhooks in the [next release](https://github.com/spree/spree/milestone/45)! -### Spree namespace +### GraphQL -All Spree models, controllers and other Ruby classes are namespaced by the `Spree` keyword, eg. `Spree::Product`. This means that those files are also located in `spree` sub-directories eg. [app/models/spree/product.rb](https://github.com/spree/spree/blob/master/core/app/models/spree/product.rb). +We're planning to deliver GraphQL in Q4 2021! -### Spree modules +## Storefronts + +Spree does not include Storefront but you can build one yourself either using + +## Spree modules Spree is divided into several modules / gems which you can install independently. -Installing Spree via [Spree Starter](https://github.com/spree/spree_starter) gives you access to all of Spree features such as Storefront, API and Admin Panel. +{% hint style="info" %} +[Spree Starter ](https://github.com/spree/spree_starter)comes with all modules pre-installed for you convenience! +{% endhint %} | Spree module | Description | | :--- | :--- | | **spree** | Data models, Services and APIs | | **spree\_backend** | Admin Panel UI \(Rails\) | -| **spree\_frontend** | Storefront \(Rails\) | | **spree\_sample** | Sample seed data | --- - -There are many other Spree-gems providing additional functionality to your Store called [Extensions](https://github.com/spree/spree-dev-docs/tree/0628094f68853238d9b13aa3b24d7b1e1b13fca4/extensions/README.md). +There are many other packages adding more features called [Extensions](../extensions/extensions.md). To change which Spree gems you would like to install you will need to modify your project `Gemfile`. @@ -58,14 +70,6 @@ gem 'spree' gem 'spree_backend' ``` -### Storefront and Admin Panel - -```ruby -gem 'spree' -gem 'spree_backend' -gem 'spree_frontend' -``` - After changing the `Gemfile` you need to run ```bash